@nibiruchain/vuepress-theme-cosmos
v0.0.185
Published
Theme for VuePress static site generator used by Nibiru and Tendermint, and Cosmos projects.
Downloads
3
Readme
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-cosmos
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-cosmos",
},
{
title: "Default resource 2",
path: "https://github.com/cosmos/vuepress-theme-cosmos",
},
],
},
],
},
},
};
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-cosmos
uses Prism to highlight language syntax in Markdown code blocks. Modify the manually imported files in TmCodeBlock.vue
to support different languages.
Versioning
Prerequisites
- Make sure the versioned branches exist.
.vuepress/config.js
- to edit versions shown on version switcherdocs/versions
- to loop through versions and generate versioned docsMakefile
/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
- add versions to
.vuepress/config.js
versions: [
{
"label": "v0.39",
"key": "v0.39"
},
{
"label": "master",
"key": "master"
}
],
- 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 preventmake build-docs
script from reading both lines (versions) of the file. cc: https://github.com/cosmos/cosmos-sdk/pull/7938
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
- Cosmos SDK Documentation —
github
—.vuepress/config.js
- Cosmos SDK Tutorials —
github
—.vuepress/config.js
- Cosmos Hub —
github
—.vuepress/config.js
- Tendermint Core Documentation —
github
—.vuepress/config.js
- Kava Documentation —
github
—.vuepress/config.js
- Ethermint Documentation —
github
—.vuepress/config.js
- Cosmwasm Documentation —
github
—.vuepress/config.js
- IBC-Go Documentation —
github
—.vuepress/config.js
Contributing
<!-- after cloning vuepress-theme-cosmos -->
$ git clone https://github.com/cosmos/vuepress-theme-cosmos.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-cosmos
$ npm run serve
License
vuepress-theme-cosmos is licensed under Apache 2.0.