Cosmos theme for VuePress

Install

# Remove previously installed version (optional)
rm -rf node_modules

# If there is no package.json file, initialize npm package
npm init

# Install or update the theme
npm install --save vuepress-theme-docs

Usage

Minimal config in .vuepress/config.js to enable the theme:

module.exports = {
  theme: "cosmos",
};

Modify scripts property in package.json:

  "scripts": {
    "serve": "vuepress dev",
    "build": "vuepress build"
  },

Run dev server

npm run serve

Build the website

npm run build

Configuration

Most of the configuration happens in the .vuepress/config.js file. All parameters all optional, except theme.

module.exports = {
  // Enable the theme
  theme: "cosmos",
  // Configure default title
  title: "Default title",
  themeConfig: {
    // Logo in the top left corner, file in .vuepress/public/
    logo: "/logo.svg",
    // Configure the manual sidebar
    header: {
      img: {
        // Image in ./vuepress/public/logo.svg
        src: "/logo.svg",
        // Image width relative to the sidebar
        width: "75%",
      },
      title: "Documentation",
    },
    // algolia docsearch
    // https://docsearch.algolia.com/
    algolia: {
      id: "BH4D9OD16A",
      key: "ac317234e6a42074175369b2f42e9754",
      index: "cosmos-sdk"
    },
    // custom must be false, topbar.banner is true to enable
    topbar: {
      banner: false
    },
    sidebar: {
      // Auto-sidebar, true by default
      auto: false,
      children: [
        // Array of sections
        {
          title: "Section title",
          children: [
            {
              title: "External link",
              path: "https://example.org/",
            },
            {
              title: "Internal link",
              path: "/url/path/",
            },
            {
              title: "Directory",
              path: "/path/to/directory/",
              directory: true,
            },
            {
              title: "Link to ./vuepress/public/foo/index.html",
              path: "/foo/",
              static: true,
            },
          ],
        },
        // Configure Resources
        {
          title: "Resources",
          children: [
            {
              title: "Default resource 1",
              path: "https://github.com/cosmos/vuepress-theme-docs",
            },
            {
              title: "Default resource 2",
              path: "https://github.com/cosmos/vuepress-theme-docs",
            },
          ],
        },
      ],
    },
  },
};

Header

themeConfig.header property is responsible for the sidebar header component.

If header is undefined, then a default image (hexagon, width 40px) is used along with a title "Documentation".

If header is a string, header is used as a path to the logo. For example, "/logo.svg" uses .vuepress/public/logo.svg in user's directory. Title string is hidden.

If header is an object and has a logo property. If logo is a string, it is used as a path to the logo with the width of 50% and title string is hidden unless header.title is defined. If logo is an object and has src property, logo.src is used as a path string with a width of 50% unless logo.width is defined.

Title string has a value of header.title if it is defined. If it is undefined and header.logo is defined, the value is "Documentation".

File configuration

Markdown files can contain YAML frontmatter. Several properties (all of which are optional) are used by the theme:

---
# title is displayed in the sidebar
title: Title of the file
# order specifies file's priority in the sidebar
order: 2
# parent is readme.md or index.md parent directory
parent:
  title: Directory title
  order: 1
---

Setting order: false removes the item (file or directory) from the sidebar. It is, however, remains accessible by means other than the sidebar. It is valid use a readme.md to set an order of a parent-directory and hide the file with order: false.

Docs search

We're currently using Algolia Docsearch to improve the search experience. You're required to join the program to use Algolia Docssearch. Once you have acquired all the necessary Algolia config keys, you can modify the $themeConfig.algolia in the config.js as such:

algolia: {
  id: "BH4D9OD16A",
  key: "ac317234e6a42074175369b2f42e9754",
  index: "cosmos-sdk"
},

Syntax highlighter

vuepress-theme-docs uses Prism to highlight language syntax in Markdown code blocks. Modify the manually imported files in TmCodeBlock.vue to support different languages.

Versioning

Prerequisites

0. Make sure the versioned branches exist.
1. .vuepress/config.js - to edit versions shown on version switcher
2. docs/versions - to loop through versions and generate versioned docs
3. Makefile/ GitHub Actions - to build versioned docs and docs with path prefixes.
   • You can use Makefile directly or
   • GitHub Actions to run make build-docs depending on your setup.

Steps

1. add versions to .vuepress/config.js

versions: [
  {
    "label": "v0.39",
    "key": "v0.39"
  },
  {
    "label": "master",
    "key": "master"
  }
],

2. edit docs/versions for Makefile to loop through and generate versioned docs.

master              master
launchpad/backports v0.39

🔔 There must be a newline at the end of versions file otherwise it will prevent make build-docs script from reading both lines (versions) of the file. cc: https://github.com/cosmos/cosmos-sdk/pull/7938

3. Makefile

https://github.com/cosmos/cosmos-sdk/blob/master/Makefile#L195 to build versioned docs and docs with path prefixes in the deployment.

Used by

1. Cosmos SDK Documentation — github — .vuepress/config.js
2. Cosmos SDK Tutorials — github — .vuepress/config.js
3. Cosmos Hub — github — .vuepress/config.js
4. Tendermint Core Documentation — github — .vuepress/config.js
5. Kava Documentation — github — .vuepress/config.js
6. Ethermint Documentation — github — .vuepress/config.js
7. Cosmwasm Documentation — github — .vuepress/config.js
8. IBC-Go Documentation — github — .vuepress/config.js

Contributing

<!-- after cloning vuepress-theme-docs -->
$ git clone https://github.com/cosmos/vuepress-theme-docs.git

<!-- example: project using vuepress-cosmos-theme -->
$ git clone https://github.com/cosmos/cosmos-sdk.git
$ cd cosmos-sdk
$ cd docs
$ npm i
$ npm link vuepress-theme-docs
$ npm run serve

License

vuepress-theme-docs is licensed under Apache 2.0.