Configuration

Configuration File Basic Configuration API Documentation Configuration Permission Documentation Configuration Reference Documentation Configuration frontmatterModeRelease Notes Configuration Sidebar Configuration Internal Document Routes Configuration Only Include Document Routes Configuration Syntax Highlighting Plugin Configuration sites.yaml Configuration Translation Configuration Editing Documentation in Code Repository Documentation Export Configuration Documentation Lint Configuration Algolia Search Configuration Sitemap Configuration

Configuration File

In most cases, we only need to use a static yaml configuration file, supporting doom.config.yaml or doom.config.yml. For complex scenarios, such as requiring dynamic configuration or custom rspress plugins, js/ts configuration files can be used, supporting multiple file formats including .js/.ts/.mjs/.mts/.cjs/.cts.

For js/ts configuration files, we need to export the configuration, which can be combined with the defineConfig function exported from @alauda/doom/config to provide type assistance:

import { defineConfig } from '@alauda/doom/config'

export default defineConfig({})

Basic Configuration

lang: Default document language. To accommodate most projects, we support both Chinese and English documents by default. The default language is en. If the current documentation project does not require multilingual support, this can be set to null or undefined.
title: Document title, displayed on the browser tab.
logo: Logo at the top left of the document, supports image URLs or file paths. Absolute paths refer to files under the public directory, relative paths refer to files relative to the current tool directory. Defaults to the Alauda logo built into the doom package.
logoText: Document title, displayed at the logo position in the top left.
icon: Document favicon, defaults to the same as logo.
base: Base path of the document, used when deploying to a non-root path, e.g., product-docs. Defaults to /.
outDir: Build output directory, defaults to dist/{base}/{version}. If specified, it changes to dist/{outDir}/{version}, where version is optional. Refer to Multi-version Build.

API Documentation Configuration

api:
  # CRD definition file paths, relative to the directory where doom.config.* is located, supports glob matching, json/yaml files
  crds:
    - docs/shared/crds/*.yaml
  # OpenAPI definition file paths, relative to the directory where doom.config.* is located, supports glob matching, json/yaml files
  openapis:
    - docs/shared/openapis/*.json
  # When rendering OpenAPI related resource definitions, they are inlined by default. To extract related resource definitions into separate files, configure the following options
  # Reference https://doom.alauda.cn/apis/references/CodeQuality.html#v1alpha1.CodeQualitySpec
  references:
    v1alpha1.CodeQualityBranch: /apis/references/CodeQualityBranch#v1alpha1.CodeQualityBranch
  # Optional, API documentation path prefix. If the current business uses gateway or other proxy services, this can be configured
  pathPrefix: /apis

Refer to API Documentation for writing documentation.

Permission Documentation Configuration

# The following resource file paths are relative to the directory where doom.config.* is located, supports glob matching, json/yaml files
permission:
  functionresources:
    # `kubectl get functionresources`
    - docs/shared/functionresources/*.yaml
  roletemplates:
    # `kubectl get roletemplates -l auth.cpaas.io/roletemplate.official=true`
    - docs/shared/roletemplates/*.yaml

Refer to Permission Documentation for writing documentation.

Reference Documentation Configuration

reference:
  - repo: alauda-public/product-doc-guide # Optional, referenced documentation repository address. If not filled, the current documentation repository address is used by default
    branch: # [string] Optional, branch of the referenced documentation repository
    publicBase: # [string] Optional, when using a remote repository, the absolute path /images/xx.png corresponds to the directory of static resources, defaults to docs/public
    sources:
      - name: anchor # Name of the referenced document, used for referencing in documentation, globally unique
        path: docs/index.mdx#介绍 # Path of the referenced document, supports anchor positioning. For remote repositories, relative to the repository root; for local, relative to the directory where doom.config.* is located
        ignoreHeading: # [boolean] Optional, whether to ignore the title. If true, the anchor title will not be displayed in the referenced document
        processors: # Optional, processors for referenced document content
          - type: ejsTemplate
            data: # ejs template parameters, accessed using `<%= data.xx %>`
        frontmatterMode: merge # Optional, mode for handling frontmatter of referenced documents, defaults to ignore. Options: ignore/merge/replace/remove

`frontmatterMode`

ignore: Ignore the frontmatter of the referenced document, keep the frontmatter of the current document.
merge: Merge the frontmatter of the referenced document. If keys overlap, the referenced document's values override the current document's.
replace: Replace the current document's frontmatter with that of the referenced document.
remove: Remove the current document's frontmatter.

Refer to Reference Documentation for writing documentation.

Release Notes Configuration

releaseNotes:
  queryTemplates:
    fixed: # JQL statements that may contain ejs templates
    unfixed:

release-notes.md

<!-- release-notes-for-bugs?template=fixed&project=DevOps -->

release-notes.mdx

{/* release-notes-for-bugs?template=fixed&project=DevOps */}

Taking template=fixed&project=DevOps as an example, fixed is the template name defined in queryTemplates. The remaining query parameter project=DevOps is passed as ejs template parameters to the fixed template, which is then processed to form a jira jql request to https://jira.alauda.cn/rest/api/2/search?jql=<jql>. This API requires authentication, and the environment variables JIRA_USERNAME and JIRA_PASSWORD must be provided to preview the effect.

sidebar:
  collapsed: false # Optional, whether the sidebar is collapsed by default. Defaults to collapsed. If the document content is small, consider setting to false.

Internal Document Routes Configuration

internalRoutes: # Optional, supports glob matching, relative to the docs directory. Routes/files matched when the CLI option `-i, --ignore` is enabled will be ignored.
  - '*/internal/**'

Only Include Document Routes Configuration

onlyIncludeRoutes: # Optional, supports glob matching, relative to the docs directory. When the CLI option `-i, --ignore` is enabled, only routes/files under this configuration will be enabled. Can be combined with `internalRoutes` to further exclude some routes.
  - '*/internal/**'
internalRoutes:
  - '*/internal/overview.mdx'

Syntax Highlighting Plugin Configuration

shiki:
  theme: # optional, https://shiki.style/themes
  langs: # optional, https://shiki.style/languages
  transformers: # optional, only available in js/ts config, https://shiki.style/guide/transformers

WARNING

Unconfigured languages will trigger warnings in the command line and fall back to plaintext rendering.

`sites.yaml` Configuration

The sites.yaml configuration file is used to configure subsite information associated with the current documentation site. It is used by External Site Components and when building single-version documentation.

- name: connectors # Globally unique name
  base: /devops-connectors # Base path for site access
  version: v1.1 # Version used for ExternalSite/ExternalSiteLink redirects when building multi-version sites

  displayName: # Site display name. If not filled or language not matched, defaults to name
    en: DevOps Connectors
    zh: DevOps 连接器

  # The following attributes are used to pull images when building the entire site. If not filled, this will be ignored during final full site packaging.
  # Usually required for subsite references, not required for parent site references.
  repo: https://github.com/AlaudaDevops/connectors-operator # Site repository address. For internal GitLab repositories, related slugs like `alauda/product-docs` can be used directly.
  image: devops/connectors-docs # Site build image, used to pull images when building the entire site.

Translation Configuration

translate:
  # System prompt, ejs template. Parameters passed in include `sourceLang`, `targetLang`, `userPrompt`, `additionalPrompts`, `terms`, `titleTranslationPrompt`.
  # Among them, `sourceLang` and `targetLang` are the strings `中文` and `英文`,
  # `userPrompt` is the global user configuration below, which may be empty.
  # `additionalPrompts` is the `additionalPrompts` configuration in document `frontmatter.i18n`, which may be empty.
  # `terms` and `titleTranslationPrompt` are prompts dynamically generated based on terminology and title tables contained in the document content, used to guide AI to translate according to terminology and title mappings, which may be empty.
  # The default system prompt is as follows and can be modified according to actual needs.
  systemPrompt: |
You are a professional technical documentation engineer, skilled in writing high-quality technical documentation in <%= targetLang %>. Please accurately translate the following text from <%= sourceLang %> to <%= targetLang %>, maintaining the style consistent with technical documentation in <%= sourceLang %>.

## Baseline Requirements
- Sentences should be fluent and conform to the expression habits of the <%= targetLang %> language.
- Input format is MDX; output format must also retain the original MDX format. Do not translate the names of jsx components such as <Overview />, and do not wrap output in unnecessary code blocks.
- **CRITICAL**: Do not translate or modify ANY link content in the document. This includes:
  - URLs in markdown links: [text](URL) - keep URL exactly as is
  - Reference-style links: [text][ref] and [ref]: URL - keep both ref and URL unchanged
  - Inline URLs: https://example.com - keep completely unchanged
  - Image links: ![alt](src) - keep src unchanged, but alt text can be translated
  - Anchor links: [text](#anchor) - keep #anchor unchanged
  - Any href attributes in HTML tags - keep unchanged
- Do not translate professional technical terms and proper nouns, including but not limited to: Kubernetes, Docker, CLI, API, REST, GraphQL, JSON, YAML, Git, GitHub, GitLab, AWS, Azure, GCP, Linux, Windows, macOS, Node.js, React, Vue, Angular, TypeScript, JavaScript, Python, Java, Go, Rust, etc. Keep these terms in their original form.
- The title field and description field in frontmatter should be translated, other frontmatter fields should retain and do not translate.
- Content within MDX components needs to be translated, whereas MDX component names and parameter keys do not.
- Do not modify or translate any placeholders in the format of __ANCHOR_N__ (where N is a number). These placeholders must be kept exactly as they appear in the source text.
- Keep original escape characters like backslash, angle brackets, etc. unchanged during translation.
- Do not add any escape characters to special characters like [], (), {}, etc. unless they were explicitly present in the source text. For example:
  - If source has "Architecture [Optional]", keep it as "Architecture [Optional]" (not "Architecture \\[Optional]")
  - If source has "Function (param)", keep it as "Function (param)" (not "Function \\(param)")
  - Only add escape characters if they were present in the original text
- Preserve and do not translate the following comments, nor modify their content:
  - {/* release-notes-for-bugs */}
  - <!-- release-notes-for-bugs -->
- Remove and do not retain the following comments:
  - {/* reference-start */}
  - {/* reference-end */}
  - <!-- reference-start -->
  - <!-- reference-end -->
- Ensure the original Markdown format remains intact during translation, such as frontmatter, code blocks, lists, tables, etc.
- Do not translate the content of the code block.
<% if (titleTranslationPrompt) { %>
<%- titleTranslationPrompt %>
<% } %>
<% if (terms) { %>
<%- terms %>
<% } %>

<% if (userPrompt || additionalPrompts) { %>
## Additional Requirements
These are additional requirements for the translation. They should be met along with the baseline requirements, and in case of any conflict, the baseline requirements should take precedence.

The text for translation is provided below, within triple quotes:
"""
<% if (userPrompt) { %>
<%- userPrompt %>
<% } %>

<% if (additionalPrompts) { %>
<%- additionalPrompts %>
<% } %>
"""
<% } %>

Editing Documentation in Code Repository

editRepoBaseUrl: alauda/doom/tree/main/docs # The https://github.com/ prefix can be omitted. Effective only when the CLI flag `-R, --edit-repo` is enabled.

Documentation Export Configuration

export:
  - name: Concepts # Optional, globally unique PDF name, defaults to the document title
    scope: '*/concepts' # Required, string or array, document scope, supports glob matching, relative to docs directory

Documentation Lint Configuration

lint:
  cspellOptions: # Optional, cspell configuration options, refer to https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-eslint-plugin#options

Algolia Search Configuration

algolia: # Optional, Algolia search configuration, effective only when the CLI flag `-a, --algolia` is enabled
  appId: # Algolia Application ID
  apiKey: # Algolia API Key
  indexName: # Algolia index name

Please use public/robots.txt for Algolia crawler verification.

INFO

Due to current architectural limitations of rspress, Algolia search functionality must be implemented via custom themes. To unify the use of related theme features, we provide the @alauda/doom/theme theme entry. Please add the following theme configuration file to enable it:

theme/index.ts

export * from '@alauda/doom/theme'

Sitemap Configuration

siteUrl: https://docs.alauda.cn # Optional, site URL used for generating sitemap, effective only when the CLI flag `-S, --site-url` is enabled

#Configuration

#TOC

#Configuration File

#Basic Configuration

#API Documentation Configuration

#Permission Documentation Configuration

#Reference Documentation Configuration

#frontmatterMode

#Release Notes Configuration

#Sidebar Configuration

#Internal Document Routes Configuration

#Only Include Document Routes Configuration

#Syntax Highlighting Plugin Configuration

#sites.yaml Configuration

#Translation Configuration

#Editing Documentation in Code Repository

#Documentation Export Configuration

#Documentation Lint Configuration

#Algolia Search Configuration

#Sitemap Configuration