Docs & Site

Hi, we've recently migrated our docs and added some new pages. If you would like to help translate this page, see the "Edit this page" link at the bottom of the page.

Documentation & site contribution guide.

Initial Setup

Fork asdf on GitHub and/or Git clone the default branch:

# clone your fork
git clone https://github.com/<GITHUB_USER>/asdf.git
# or clone asdf
git clone https://github.com/asdf-vm/asdf.git

The tools for Docs site development are managed with asdf in the docs/.tool-versions. Add the plugins with:

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs

Install the tool version(s) with:

asdf install

Install Node.js dependencies from docs/package.json:

npm install

Development

Vuepress (v2)open in new window is the Static Site Generator (SSG) we use to build the asdf documentation site. It was chosen to replace Docsify.jsopen in new window as we would like to support an HTML only fallback when users do not have JavaScript available or enabled. This was not possible with Docsify. Other than this, the feature-set is largely the same, with the focus on writing Markdown files with minimal configuration.

package.json contains the scripts required for development:

File not found

To start the local development server:

npm run dev

Format the code before committing:

npm run format

Pull Requests, Releases & Conventional Commits

asdf is using an automated release pipeline which relies on Conventional Commits in PR titles. Detailed documentation found in the core contribution guide.

When creating a PR for documentation changes please make the PR title with the Conventional Commit type docs in the format docs: <description>.

Vuepress

Configuration of the site is contained within a few JavaScript files with JS Objects used to represent the config. They are:

To simplify the root config, the larger JS Objects representing the navbar and sidebar configuration have been extracted and separated by their locale. See both in:

  • docs/.vuepress/navbar.js
  • docs/.vuepress/sidebar.js

With the official documentation for these configs living in the Default Theme Referenceopen in new window.

I18n

Vuepress has first-class support for internationalization. The root config docs/.vuepress/config.js defines the supported locales with their URL, title in the selection dropdown menu and navbar/sidebar configs references.

The navbar/sidebar configs are captured in the aforementioned config files, separated by locale and exported individually.

The markdown content for each locale must fall under a folder with the same name as the keys for locales in the root config. That is:

{
  ...
  themeConfig: {
    locales: {
      "/": {
        selectLanguageName: "English (US)",
        sidebar: sidebar.en,
        navbar: navbar.en
      },
      "/pt-BR/": {
        selectLanguageName: "Brazilian Portuguese",
        sidebar: sidebar.pt_br,
        navbar: navbar.pt_br
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/pt-BR/ will require the same set of markdown files located under docs/pt-BR/, like so:

docs
├─ README.md
├─ foo.md
├─ nested
│  └─ README.md
└─ pt-BR
   ├─ README.md
   ├─ foo.md
   └─ nested
      └─ README.md

The official Vuepress i18n documentationopen in new window goes into more detail.