Categorygithub.com/rollchains/spawndocs
package
0.50.10
Repository: https://github.com/rollchains/spawn.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
1
Dependents
1
Files
2 SLOC

# README

Spawn Documentation

Welcome to the Spawn documentation! This website is built using Docusaurus 2, a modern static website generator.

Configuration

Docusaurus configuration file is located at ./docusaurus.config.js. This file contains the configuration for the sidebar, navbar, footer, and other settings. Sidebars are created in ./sidebars.js.

Local Development and Deployment

Installation

npm install

Local Development

npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. However, in the local development environment, some plugins like @docusaurus/plugin-client-redirects, will not work at all. This is why the landing page is an error page in the local development environment, and why you have to click on the correct docs version to see the documentation. This is not the case in the production environment. To view the production environment, you must build and serve the website locally.

Build

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

Serve

npm run serve

This command starts a local production server and opens up a browser window.

Updating the Documentation

The documentation website is autogenerated from the markdown files found in docs directory. Each directory in ./docs/ represents a category to be displayed in the sidebar. If you create a new directory, you must create a _category_.json file in that directory with the following contents:

{
  "label": "Sidebar Label",
  "position": 1, // position of the category in the sidebar
  "link": null
}

The position key above is used to order the categories in the sidebar. This position key pertains to the order of this category in the parent directory.

If you create a new markdown file within a category (.docs/ directory is itself a category), you must add the following frontmatter to the top of the markdown file:

---
title: Title of the file # title of the file in the sidebar
sidebar_label: Sidebar Label # title of the file in the sidebar
sidebar_position: 1 # position of the file in the sidebar
slug: /migrations/v5-to-v6 # the url of the file
---

The link key in _category_.json determines if the category has an introductory page that comes before any content pages. If link is null, then the category does not have an introductory page. If there is a markdown file you wish to link, you should do

{
  "label": "Sidebar Label",
  "position": 1, // position of the category in the sidebar
  "link": { "type": "doc", "id": "intro" }
}

The id key can be defined in the frontmatter of the markdown file. Or, you can use the id tag as an extension to the url of the current page. For example, the following frontmatter on a markdown file in the same directory as the _category_.json file shown above will link to the markdown file:

---
title: Title
sidebar_label: Sidebar Label
sidebar_position: 0 # should be zero for intro pages
slug: /ibc/upgrades/intro
---

Code Blocks

Code blocks in docusaurus are super-powered, read more about them here. Three most important features for us are:

  1. We can add a title to the code block, which will be displayed above the code block. (This should be used to display the file path of the code block.)
  2. We can add a reference tag to the code block, which will reference github to create the code block. You should always use hyperlinks in reference codeblocks. Here is what a typical code block should look like:
```go reference title="modules/apps/transfer/keeper/keeper.go"
https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/apps/transfer/keeper/keeper.go#L19-L31
```
  1. We can highlight lines in the code block by adding // highlight-next-line before the line we want to highlight. For example, we should use this to highlight diffs. Here is an example:
```go
import (
  ...
  // highlight-next-line
+ ibctm "github.com/cosmos/ibc-go/v6/modules/light-clients/07-tendermint"
  ...
)
```

Links

In docusaurus, there are three ways to link to other pages:

  1. File Paths (relative or absolute)
  2. URLs (relative or absolute)
  3. Hyperlinks

In this section, we will discuss when to use each.

Static Assets

Static assets are the non-code files that are directly copied to the build output. They include images, stylesheets, favicons, fonts, etc.

By default, you are suggested to put these assets in the static/ directory. Every file you put into that directory will be copied into the root of the generated build folder with the directory hierarchy preserved. E.g. if you add a file named sun.jpg to the static folder, it will be copied to build/sun.jpg.

These assets should be referenced using absolute URLs. For example, if you have an image in static/img/cosmos-logo-bw.png, you should reference it using /img/cosmos-logo-bw.png.

Raw Assets

If you want to link a raw file, you should link to it using @site + its base path. For example, if you want to link to the raw markdown file /architecture/adr.template.md, you should use the absolute URL @site/architecture/adr.template.md.

Technical writing course

Google provides a free course for technical writing.

Terminology

  • Current version: The version placed in the .docs/ folder. This version is the one that is displayed on the website by default, referred to as next.
  • Latest version: This version is defined in ./docusaurus.config.js file under the lastVersion key.

Overview

A typical versioned doc site looks like below:

docs/
├── sidebars.json          # sidebar for the current docs version
├── docs/                  # docs directory for the current docs version
│   ├── 01-foo/
│   │   └── 01-bar.md      # https://mysite.com/docs/next/01-foo/01-bar
│   └── 00-intro.md        # https://mysite.com/docs/next/00-intro
├── versions.json          # file to indicate what versions are available
├── versioned_docs/
│   ├── version-v1.1.0/
│   │   ├── 01-foo/
│   │   │   └── 01-bar.md  # https://mysite.com/docs/01-foo/01-bar
│   │   └── 00-intro.md
│   └── version-v1.0.0/
│       ├── 01-foo/
│       │   └── 01-bar.md  # https://mysite.com/docs/v1.0.0/01-foo/01-bar
│       └── 00-intro.md
├── versioned_sidebars/
│   ├── version-v1.1.0-sidebars.json
│   └── version-v1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

The ./versions.json file is a list of version names, ordered from newest to oldest.

Tagging a new version

It is possible to tag the current version of the docs as a new version. This will create the appropriate files in ./versioned_docs/ and ./versioned_sidebars/ directories, and modify the ./versions.json file. To do this, run the following command:

npm run docusaurus docs:version v7.1.0

Adding a new version

To add a new version:

  1. Create a new directory in ./versioned_docs/ called version-vX.Y.Z where X.Y.Z is the version number. This directory should contain the markdown files for the new version.
  2. Create a new file in ./versioned_sidebars/ called version-vX.Y.Z-sidebars.json. This file should contain the sidebar for the new version.
  3. Add the version to the ./versions.json file. The list should be ordered from newest to oldest.
  4. If needed, make any configuration changes in ./docusaurus.config.js. For example, updating the lastVersion key in ./docusaurus.config.js to the latest version.

Updating an existing version

You can update multiple docs versions at the same time because each directory in ./versioned_docs/ represents specific routes when published. Make changes by editing the markdown files in the appropriate version directory.

Deleting a version

When a version is no longer supported, you can delete it by removing it from versions.json and deleting the corresponding files in ./versioned_docs/ and ./versioned_sidebars/.

# Variables

go:embed versioned_docs/version-v0.50.x/**/*.md.