Docs & Site

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

Node.js: JavaScript runtime built on Chrome's V8 JavaScript engine.

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

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:

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

Vitepress

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

docs/.vitepress/config.js: the root config file for the site. Read the VitePress documentation for it's spec.

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:

// 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:

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.

3.9 KiB Raw Blame History