Docs & Site

Documentation & site contribution guide.

Initial Setup

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

# clone your fork
git clone<GITHUB_USER>/asdf.git
# or clone asdf
git clone

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

asdf plugin add nodejs

Install the tool version(s) with:

asdf install

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

npm install


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:

  "scripts": {
    "dev": "vuepress dev .",
    "build": "vuepress build .",
    "format": "npx -y prettier --write '{.vuepress/{config,navbar,sidebar}.js,./**/*.md}'"
  "devDependencies": {
    "@vuepress/plugin-active-header-links": "^2.0.0-beta.48",
    "@vuepress/plugin-search": "^2.0.0-beta.48",
    "@vuepress/plugin-shiki": "^2.0.0-beta.48",
    "vuepress": "^2.0.0-beta.48"


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>.


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.


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

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

├─ nested
│  └─
└─ pt-BR
   └─ nested

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