Configuration Reference

The config.yaml file is the core control panel for your documentation generation. By adjusting its settings, you can control how AI generates documentation, including document structure, content style, and language support. This guide provides detailed explanations for each configuration field to help you fine-tune according to your project needs.

Overview#

The config.yaml file is the primary configuration file for AIGNE DocSmith. It stores all configuration parameters in YAML format. When you run commands such as create, update, or translate, DocSmith reads this file to understand your configuration requirements.

  • File name: config.yaml
  • Location: .aigne/doc-smith/config.yaml (relative to your project root)
  • Format: YAML (UTF-8)

Through this file, you can set documentation goals, target readers, content generation rules, document structure, multilingual support, and publishing settings.

Creating and Updating Configuration#

The config.yaml file is automatically created when you first use DocSmith.

Creating:

You can create this file in two ways:

  1. During initial generation: Running aigne doc create in a new project will launch an interactive wizard to create the config.yaml file before starting the generation process.
  2. Create separately: Running aigne doc init will launch the same wizard to create the configuration file without immediately generating documentation.

aigne doc init

aigne doc init

Updating:

You can update your configuration using one of the following methods:

  1. Edit the file directly: Open .aigne/doc-smith/config.yaml in a text editor and modify the fields.
  2. Use the interactive wizard: Run aigne doc init again. The wizard will load your existing settings and guide you through updates.

Configuration Parameters#

Fields in config.yaml are organized by functional groups. The following sections explain each parameter in detail.

Project Basics#

These fields define basic project information used for document branding, search engine optimization, and social media sharing.

projectName
string
required

The display name of your project, which appears in document titles, navigation bars, and other branding elements. It is recommended to keep it under 50 characters to ensure it displays completely in various interfaces.

projectDesc
string
required

A brief description of your project, used for search engine optimization and social sharing preview text. It is recommended to keep it under 150 characters, clearly and concisely describing the core value of your project.

projectLogo
string

The URL or local file path to your project logo. The logo will be displayed in document website headers, browser tab icons, and social media sharing previews. Supports full URLs (e.g., https://example.com/logo.png) or relative paths (e.g., ./assets/logo.png).

AI Thinking Configuration#

These settings control the depth of AI thinking and processing intensity when generating document content, affecting the balance between generation quality and speed.

thinking
object

Configure AI reasoning intensity.

1 subfields

Documentation Strategy#

These settings define documentation generation strategy, including document goals, reader types, content depth, etc., directly affecting how AI organizes and generates content.

documentPurpose
array
required

Define the primary goals of the documentation (multiple selection allowed). Options include: getStarted (quick start guide), completeTasks (task operation manual), findAnswers (reference query manual), understandSystem (system understanding documentation), solveProblems (troubleshooting guide), and mixedPurpose (comprehensive documentation). Choosing different goals affects document structure and content organization.

targetAudienceTypes
array
required

Specify target reader types (multiple selection allowed). Options include: endUsers (general users), developers (developers), devops (operations engineers), decisionMakers (technical decision makers), supportTeams (technical support teams), and mixedTechnical (mixed technical backgrounds). Choosing different reader types affects document language style, technical depth, and example types.

readerKnowledgeLevel
string
required

Set the technical knowledge level of target readers. Options include: completeBeginners (complete novices, need detailed explanations), domainFamiliar (familiar with related domains but first-time users of this tool), experiencedUsers (experienced users, need reference manuals), emergencyTroubleshooting (emergency troubleshooting, need quick solutions), and exploringEvaluating (evaluating suitability, need quick understanding).

documentationDepth
string
required

Control the level of detail in documentation. Options include: essentialOnly (core features only, concise version), balancedCoverage (balanced coverage, recommended for most projects), comprehensive (comprehensive coverage, including all features and edge cases), and aiDecide (automatically decided by AI based on code complexity).

targetAudience
string

A detailed description of target readers, used to supplement targetAudienceTypes settings. Can describe readers' specific backgrounds, use cases, tech stacks, or special requirements. Supports multi-line text, helping AI better understand reader needs.

rules
string

Provide detailed generation rules and guidance for AI, including content structure, writing style, format requirements, etc. This is one of the most important configuration fields, directly affecting the quality and style of generated documentation. Supports Markdown format, allowing multi-line rules. It is recommended to specify your specific requirements in detail, such as: "avoid using vague words", "must include code examples", etc.

Language#

Configure the primary language and any additional languages for translation.

locale
string
default:en

The primary language of the documentation, using standard language codes. Common values include: en (English), zh (Simplified Chinese), zh-TW (Traditional Chinese), ja (Japanese), etc. Documentation will first be generated in this language, then can be translated to other languages.

translateLanguages
array

A list of target languages for translation (multiple selection allowed). Each language code will generate a complete set of translated documentation. For example, setting ["zh", "ja"] will generate Simplified Chinese and Japanese versions of the documentation. Note: Do not include language codes that are the same as locale.

Data Sources#

These settings specify the reference materials used by AI when analyzing source code and documentation, directly affecting the quality and accuracy of generated documentation.

sourcesPath
array
required

A list of source code and documentation paths for AI analysis. This is the most important configuration field because AI will only generate documentation based on content in these paths. It is recommended to include: README files, main source code directories, configuration files (such as package.json, aigne.yaml), existing documentation directories, etc. Supports multiple formats: directory paths (e.g., ./src), file paths (e.g., ./README.md), glob patterns (e.g., src/**/*.js), and remote URLs.

Output and Deployment#

Configure the save location for generated documentation and the publishing address.

docsDir
string
default:./aigne/doc-smith/docs

The directory where generated documentation is saved. All generated Markdown files will be saved in this directory. If the directory does not exist, DocSmith will automatically create it. It is recommended to use relative paths for easier project migration.

appUrl
string

The access address after documentation is published. After running the publish command, DocSmith will automatically update this field. Usually does not need to be set manually unless you want to specify a particular publishing address.

Media and Display#

These settings control how media assets such as images are handled.

media
object

Media file processing settings.

1 subfields

Diagramming Configuration#

Control diagram generation behavior and AI effort level.

diagramming
object

Diagram generation configuration.

1 subfields

System-Managed Fields#

These fields are automatically managed by DocSmith and generally do not require manual editing. Modifying these fields may cause unexpected issues.

lastGitHead
string

The Git commit hash from the last documentation generation. DocSmith uses this value to determine which files have changed, enabling incremental updates. Do not modify manually.

boardId
string

The unique identifier for the documentation publishing board, automatically generated by the system. Do not modify manually, otherwise it will disconnect the project from its publishing history and may lose published documentation.

checkoutId
string

A temporary identifier used during document deployment, automatically managed by the system. Do not modify manually.

shouldSyncBranding
string

A temporary variable controlling whether to sync branding, automatically managed by the system. Do not modify manually.

Applying Changes#

After modifying the config.yaml file, you need to run the corresponding commands for the changes to take effect. Different fields require different commands, as shown in the table below.

Field

Command to Apply Changes

Description

documentPurpose, targetAudienceTypes, readerKnowledgeLevel, documentationDepth, locale

aigne doc clear && aigne doc create

These fields affect the overall document structure and require clearing old documentation and regenerating.

rules, targetAudience, media.minImageWidth, thinking.effort, diagramming.effort

aigne doc update

These fields only affect content generation methods and can directly update existing documentation without regeneration.

sourcesPath

aigne doc clear && aigne doc create or aigne doc update

After adding new data sources, you can choose to fully regenerate or incrementally update. It is recommended to use create when adding for the first time, and update for subsequent additions.

translateLanguages

aigne doc translate

After adding new translation languages, run this command to generate documentation versions in the corresponding languages.

projectName, projectDesc, projectLogo, appUrl

aigne doc publish

These fields are mainly used for metadata during publishing. After modification, republish to take effect.

docsDir

aigne doc create

After modifying the output directory, the next documentation generation will save to the new directory.

Complete Configuration Example#

Below is the complete config.yaml file from the AIGNE DocSmith project itself, demonstrating a real-world configuration.

config.yaml

# Project information for documentation publishing
projectName: AIGNE DocSmith
projectDesc: AIGNE DocSmith is a powerful, AI-driven documentation creation tool built on the AIGNE Framework. It automates the creation of detailed, structured, and multi-language documentation directly from your source code.
projectLogo: https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg

# =============================================================================
# Documentation Configuration
# =============================================================================

# Purpose: What's the main outcome you want readers to achieve?
documentPurpose:
  - getStarted
  - completeTasks

# Target Audience: Who will be reading this most often?
targetAudienceTypes:
  - endUsers

# Reader Knowledge Level: What do readers typically know when they arrive?
readerKnowledgeLevel: completeBeginners

# Documentation Depth: How comprehensive should the documentation be?
documentationDepth: comprehensive

# Custom Rules: Define specific documentation generation rules and requirements

See all 39 lines

Summary#

The config.yaml file is the core of controlling documentation generation. By properly configuring project information, documentation strategy, and data sources, you can guide AI to generate high-quality documentation that meets your project needs. It is recommended to start with basic configuration and gradually adjust parameters based on actual results.

Interactive Mode (Beta)
Initial Setup