Skip to content

Latest commit

 

History

History
234 lines (175 loc) · 9.49 KB

start.mdx

File metadata and controls

234 lines (175 loc) · 9.49 KB
sourceSHA
abdacac359849f6bc46d4b115a537545544edd8d5bee65fe8732cd3cea8ec8e9

Start {#start}

Create Project {#create}

First, you can create a new directory using the following command:

mkdir my-docs && cd my-docs

Run npm init -y to initialize a project. You can use npm, yarn, or pnpm to install doom:

Then, create files using the following commands:

# Create docs directory, supporting both Chinese and English by default
mkdir docs/en && echo '# Hello World' > docs/en/index.md
mkdir docs/zh && echo '# 你好世界' > docs/zh/index.md

Add the following scripts in package.json:

{
  "scripts": {
    "dev": "doom dev",
    "build": "doom build",
    "new": "doom new",
    "serve": "doom serve",
    "translate": "doom translate",
    "export": "doom export"
  }
}

Then initialize a configuration file doom.config.yml:

title: My Docs

Also, create a tsconfig.json file with the following content:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "target": "ESNext",
  },
  "mdx": {
    "checkMdx": true,
  },
}

Lastly, create a global.d.ts file with the following content:

/// <reference types="@alauda/doom/runtime" />

Now you can use the global components provided by doom in your .mdx files with type safety.

Command Line Tool {#cli}

doom -h

# output
Usage: doom [options] [command]

Doctor Doom making docs.

Options:
  -V, --version                   output the version number
  -c, --config <config>           Specify the path to the config file
  -v <version>                    Specify the version of the documentation, can also be `unversioned` or `unversioned-x.y`
  -b, --base <base>               Override the base of the documentation
  -p, --prefix <prefix>           Specify the prefix of the documentation base
  -f, --force [boolean]           Force to
                                  1. fetch latest reference remotes or scaffolding templates, otherwise use local cache
                                  2. translate ignore hash equality check and original text (default: false)
  -i, --ignore [boolean]          Ignore internal routes (default: false)
  -d, --download [boolean]        Display download pdf link on nav bar (default: false)
  -e, --export [boolean]          Run or build in exporting PDF mode, `apis/**` and `*/apis/**` routes will be ignored automatically (default: false)
  -I, --include <language...>     Include **only** the specific language(s), `en ru` for example
  -E, --exclude <language...>     Include all languages except the specific language(s), `ru` for example
  -o, --out-dir <path>            Override the `outDir` defined in the config file or the default `dist/{base}/{version}`, the resulting path will be `dist/{outDir}/{version}`
  -r, --redirect <enum>           Whether to redirect to the locale closest to `navigator.language` when the user visits the site, could be `auto`, `never` or `only-default-lang` (default: "only-default-lang")
  -R, --edit-repo [boolean|url]   Whether to enable or override the `editRepoBaseUrl` config feature, `https://github.com/` prefix could be omitted (default: false)
  -n, --no-open [boolean]         Do not open the browser after starting the server
  -h, --help                      display help for command

Commands:
  dev [options] [root]            Start the development server
  build [root]                    Build the documentation
  preview|serve [options] [root]  Preview the built documentation
  new [template]                  Generate scaffolding from templates
  translate [options] [root]      Translate the documentation
  export [options] [root]         Export the documentation as PDF, `apis/**` and `*/apis/**` routes will be ignored automatically
  help [command]                  display help for command

Start Development Service {#dev}

Run yarn dev to start the development service, and the browser will automatically open the documentation homepage.

doom dev -h

# output
Usage: doom dev [options] [root]

Start the development server

Arguments:
  root                      Root directory of the documentation

Options:
  -H, --host [host]         Dev server host name
  -P, --port [port]         Dev server port number
  -l, --lazy [boolean]      Whether to enable `lazyCompilation`, which could improve the compilation performance (default: false)
  -h, --help                display help for command

Production Build {#build}

Run yarn build to build the production environment code. After the build is completed, static files will be generated in the dist directory.

Local Preview {#serve}

Run yarn serve to preview the built static files. Note that if you used the -b, -p options to build, the same options are also required when previewing.

Use Scaffolding Templates {#new}

Run yarn new to generate projects, modules, or documentation using scaffolding templates.

Translate Documentation {#translate}

doom translate -h

# output
Usage: doom translate [options] [root]

Translate the documentation

Arguments:
  root                     Root directory of the documentation

Options:
  -s, --source <language>  Document source language, one of en, zh, ru (default: "en")
  -t, --target <language>  Document target language, one of en, zh, ru (default: "zh")
  -g, --glob <path...>     Glob patterns for source dirs/files
  -C, --copy [boolean]     Whether to copy relative assets to the target directory instead of following links (default: false)
  -h, --help               display help for command

  • The -g, --glob parameter is required and can specify the directory or path of files to be translated, supporting glob syntax. Note that the parameter value must be quoted; otherwise, command line parsing may cause unexpected behavior. Examples:

    1. yarn translate -g abc xyz will translate all documents in the <root>/<source>/abc and <root>/<source>/xyz directories to <root>/<target>/abc and <root>/<target>/xyz.
    2. yarn translate -g '*' will translate all document files under <root>/<source>.

  • The -C, --copy parameter is optional, determining whether to copy local resource files to the target directory when a target file does not exist. The default is false, which means changing the reference path of the resource file to the source path. Examples:

    • When this parameter is enabled:
      1. Translating /<source>/abc.jpg will copy <root>/public/<source>/abc.jpg to <root>/public/<target>/abc.jpg and change the document's reference path to /<target>/abc.jpg.
      2. In <root>/<source>/abc.mdx, when translating the reference ./assets/xyz.jpg, it will copy <root>/<source>/assets/xyz.jpg to <root>/<target>/assets/xyz.jpg, keeping the image reference path unchanged.
      3. In <root>/<source>/abc.mdx, when translating the reference ./assets/<source>/xyz.jpg, it will copy <root>/<source>/assets/<source>/xyz.jpg to <root>/<target>/assets/<target>/xyz.jpg and change the document's reference path to ./assets/<target>/xyz.jpg.
    • If this parameter is not enabled:
      1. Translating /<source>/abc.jpg, if <root>/public/<target>/abc.jpg already exists, will change the document's reference path to /<target>/abc.jpg; otherwise, it will keep the image reference path unchanged.
      2. In <root>/<source>/abc.mdx, when translating the reference ./assets/<source>/xyz.jpg, if <root>/<target>/assets/<target>/xyz.jpg already exists, it will change the document's reference path to ./assets/<target>/xyz.jpg; otherwise, it will change to ../<source>/assets/<target>/xyz.jpg.

:::warning In particular, when using -g '*' for full translation, the file lists of the source and target directories will be compared. Any unmatched target files, excluding internalRoutes, will be automatically deleted. :::

:::tip The translation function requires the local environment variable AZURE_OPENAI_API_KEY to be configured. Please contact your team leader for this information. :::

Metadata can be used in the document to control translation behavior:

i18n:
  title:
    en: DevOps Connectors
  additionalPrompts: 'In this text, Connectors is a proper noun, do not translate it.'
  disableAutoTranslation: false
title: DevOps 连接器

Export PDF {#export}

:::warning Please run the yarn build operation before executing the export operation. :::

doom export -h

# output
Usage: doom export [options] [root]

Export the documentation as PDF, `apis/**` and `*/apis/**` routes will be ignored automatically

Arguments:
  root               Root directory of the documentation

Options:
  -H, --host [host]  Serve host name
  -P, --port [port]  Serve port number (default: "4173")
  -h, --help         display help for command

Run yarn export to export the documentation as a PDF file. Note that if you used -b, -p options to build, the same options are also required during export.

The export functionality relies on playwright. In the pipeline, please use build-harbor.alauda.cn/frontend/playwright-runner:doom as the base image for dependency installation and documentation building. You can set the following environment variable locally to speed up downloads:

PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"