CLI

npx gem-book -h

Commands

# Start the dev server, documents are read on each request, changes reload the page
npx gem-book [dev] [docs-dir]

# Build the website, every page is prerendered into dist/web
npx gem-book build [docs-dir]

# Build the website and serve dist/web to preview it locally
npx gem-book serve [docs-dir]

The documents directory defaults to the current directory, it is also the static resource directory: images and other files referenced in documents are output with the website (Markdown files are not output).

Options

`-t, --title <title>`

Specify the website title, read from the title of package.json by default or use the current working directory name.

`--i18n`

Specify whether the document directory supports internationalization.

`--port <port>`

Specify the port of the dev server.

`--config <path>`

Specify the config file path, default is gem-book.cli.json in the current working directory.

Config file

The other settings are in the config file gem-book.cli.json, for example:

{
  "$schema": "./schema.json",
  "title": "GemBook",
  "icon": "../../logo.png",
  "i18n": true,
  "homeMode": true,
  "site": "https://book.gemjs.org",
  "sourceBranch": "docs",
  "ga": "G-PZYZ441YD3",
  "port": 8090,
  "global": {
    "hello": "Hello World!"
  },
  "docsearch": {
    "appId": "05KK61XW6A",
    "apiKey": "b6738e2ef6d977e01ab3a325b91937e1",
    "indexName": "book-gemjs"
  }
}

TIP
Add "$schema": "https://unpkg.com/gem-book/schema.json" to get type hints.

`title`

Same as --title.

`icon`

The icon path (relative to the current working directory) or URL, it is displayed in the navigation bar and used as the favicon.

`i18n`

Same as --i18n.

`fallbackLanguage`

The language of the documents when internationalization is not enabled, otherwise the default language, default is en.

`homeMode`

Display the README.md / index.md in the document root directory in the homepage layout, and the document metadata is required.

`ignored`

Ignored documents or directories, relative to the language directory. A rule without / matches the name in any directory, * matches any characters in a name and ** matches any levels of directories, for example ["drafts", "*.draft.md", "guide/**"]. node_modules and names starting with . are always ignored.

`versions`

Old versions of the documents, newest first, e.g. ["v2", "v1"], see Versioning.

`displayRank`

Display the value used for sorting in the URL.

`github`

The GitHub or GitLab repository address, it is rendered in the navigation bar and used to generate the "edit this page" link and the last updated time, read from the origin of the local Git repository by default.

`sourceBranch`

The branch of the "edit this page" link, default is the current branch.

`nav`

Links of the navigation bar, external links are displayed on the right, links with the title twitter, discord etc. are displayed as icons:

{
  "nav": [
    { "title": "Example", "link": "https://example.com" },
    { "title": "Twitter", "link": "https://twitter.com/xxx" }
  ]
}

`footer`

The footer content, Markdown format.

`theme`

The name of a built-in theme or the path of a theme file, see Theme.

`global`

Global variables, used by <gbp-var>.

`importMap`

Path prefix mapping, used by the src of plugins such as <gbp-raw> and by <gbp-api> to read the parent class, for example mapping a package name to its source directory:

{
  "importMap": {
    "@mantou/tap-ui/": "node_modules/@mantou/tap-ui/src/"
  }
}

When the environment variable GEM_BOOK_REPLACE is set, the esm.sh modules in <gbp-example> and <gbp-import> are also mapped to local files and bundled with the website, e.g. https://esm.sh/@mantou/tap-ui/elements/button => node_modules/@mantou/tap-ui/src/elements/button.ts, useful when developing a UI library: GEM_BOOK_REPLACE=true gem-book docs.

`plugins`

Site-wide plugins, paths of modules (relative to the current working directory) or package names, they are bundled with the website and loaded on every page, see Custom elements:

{
  "plugins": ["docs/plugins/hello.ts"]
}

`docsearch`

The search of the website, see <gbp-docsearch>.

`comment`

The comment of the pages, see <gbp-comment>.

`ga`

Google Analytics v4 ID, only used by the built website.

`site`

The website URL, for example https://book.gemjs.org, sitemap.xml is generated when building, the canonical and hreflang links of pages use full URLs.

`port`

Same as --port.