asdf/docs/contributing-doc-site.md

Improvements

Here is a list of improvements we are looking at making to the documentation. If you wish to contribute, try something out here:

• customise the docsify theme
• cover-page background image
• cover-page/readme gif of a terminal using asdf showing it's features (automatic version switching, .tool-versions with multiple runtime configs)
• custom doc site domain
• change the typography
• get a logo?
• improve "edit on GitHub" button/link
• add asdf to awesome-docsify showcase

Setup Your Environment

We're using:

• Node.js v10.15.0 to support the other required tools
• docsify to create our documentation site
• prettier to format our markdown files

Install Dependencies

We are trying to avoid polluting the core repo with tooling for this documentation site. As such, it would be great if you could install these development tools globally so we don't need to commit them to this project.

npm i docsify-cli prettier -g

Serve the Site

From the root of this repo run:

docsify serve docs

Format before Committing

From the root of this repo run:

prettier --write "docs/**/*.md"

Translations

It would be great to provide translations for other languages.

Docsify makes adding new languages quite easy. Look in docs/index.html for commented out zh-cn examples.

Adding a new Translation

1. create a folder in docs/ for the new translation

   docs/
   docs/zh-cn/
   

2. copy file from root docs/_404.md to new folder docs/zh-cn/_404.md

   docs/_404.md
   docs/zh-cn/_404.md
   

3. replace text with translated text.
4. repeat for all files.
5. add a link to the new translation in _navbar.md.
6. run prettier before committing.

For more information, see the Configuration docsify docs, the Custom navbar docsify docs, and have a look at their own index.html's search section.