asdf

English

日本語
Brazilian Portuguese
简体中文

English

日本語
Brazilian Portuguese
简体中文

Appearance

Docs & Site ​

Documentation & site contribution guide.

Initial Setup ​

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

shell
# clone your fork
git clone https://github.com/<GITHUB_USER>/asdf.git
# or clone asdf
git clone https://github.com/asdf-vm/asdf.git
# 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:

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

Install the tool version(s) with:

shell
asdf install
asdf install
  • Node.js: JavaScript runtime built on Chrome's V8 JavaScript engine.

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

shell
npm install
npm install

Development ​

VitePress (v2) is the Static Site Generator (SSG) we use to build the asdf documentation site. It was chosen to replace Docsify.js and subsequently VuePress 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 & VitePress quicly supplanted VuePress. 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:

@code json{3-5}

To start the local development server:

shell
npm run dev
npm run dev

Format the code before committing:

shell
npm run format
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>.

Vitepress ​

Configuration of the site is contained within a few TypeScript 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/.vitepress/navbars.js
  • docs/.vitepress/sidebars.js

With the official documentation for these configs living in the Default Theme Reference.

I18n ​

VitePress has first-class support for internationalization. The root config docs/.vitepress/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:

js
// docs/.vitepress/config.js
export default defineConfig({
  ...
  locales: {
    root: {
      label: "English",
        lang: "en-US",
        themeConfig: {
        nav: navbars.en,
          sidebar: sidebars.en,
      },
    },
    "pt-br": {
      label: "Brazilian Portuguese",
        lang: "pr-br",
        themeConfig: {
        nav: navbars.pt_br,
          sidebar: sidebars.pt_br,
      },
    },
    "zh-hans": {
      label: "简体中文",
        lang: "zh-hans",
        themeConfig: {
        nav: navbars.zh_hans,
          sidebar: sidebars.zh_hans,
      },
    },
  },
})
// docs/.vitepress/config.js
export default defineConfig({
  ...
  locales: {
    root: {
      label: "English",
        lang: "en-US",
        themeConfig: {
        nav: navbars.en,
          sidebar: sidebars.en,
      },
    },
    "pt-br": {
      label: "Brazilian Portuguese",
        lang: "pr-br",
        themeConfig: {
        nav: navbars.pt_br,
          sidebar: sidebars.pt_br,
      },
    },
    "zh-hans": {
      label: "简体中文",
        lang: "zh-hans",
        themeConfig: {
        nav: navbars.zh_hans,
          sidebar: sidebars.zh_hans,
      },
    },
  },
})

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

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

The official VitePress i18n documentation goes into more detail.