# Generate documentation · Chromia Docs (concept)

> This topic explains how to generate a documentation site from your Rell source code and how to customize it to match your project's branding and requirements.

Source: https://docs.chromia.com/build/cli/generating-doc-site/

# Generate documentation

On this page

* [Overview](#overview)
* [Generate a documentation site](#generate-a-documentation-site)
* [Configure document generation](#configure-document-generation)
* [Add additional content](#add-additional-content)
* [Example custom content file](#example-custom-content-file)
* [Customize styling](#customize-styling)
* [Example custom stylesheet](#example-custom-stylesheet)
* [Add custom assets](#add-custom-assets)
* [Add additional modules](#add-additional-modules)
* [Configuration example](#configuration-example)
* [Usage notes](#usage-notes)
* [Troubleshooting](#troubleshooting)
* [Navigation bar not showing](#navigation-bar-not-showing)
* [Custom styling not applied](#custom-styling-not-applied)

This topic explains how to generate a documentation site from your Rell source code and how to customize it to match
your project's branding and requirements.

## Overview

The Chromia CLI provides a built-in command to generate a documentation site from your Rell source code.

* API documentation automatically generated from Rell source code together with corresponding [RellDoc](https://docs.chromia.com/rell/rell-doc/)
  comments in your code.
* Custom content pages that you can add
* Customizable styling and branding

## Generate a documentation site

To generate a documentation site, run the following command in your project directory:

Terminal

```
chr generate docs-site
```

You can view the generated site by opening `build/docs-site/index.html` in your web browser.

The generated site contains JS code to provide a navigation bar. Although you can open the index.html page in your
browser, the best experience is achieved by hosting the site on a web server which will enable the navigation.

warning

To view the navigation bar, the generated site needs to run on a web server, see
[Navigation bar not showing](#navigation-bar-not-showing).

## Configure document generation

Document generation is configured in the `docs` section of your `chromia.yml` file. Here's an example configuration:

YAML

```
docs:
  title: "My Rell Dapp" # Title of the documentation site
  footerMessage: "© 2024 Copyright MyCompany" # Custom footer message
  customAssets: # Custom assets to include
    - docs-assets/logo.png
    - docs-assets/favicon.ico
  customStyleSheets: # Custom CSS stylesheets
    - docs-assets/custom-styles.css
  additionalContent: # Additional markdown content
    - docs-assets/getting-started.md
    - docs-assets/tutorials/basic-usage.md
  additionalModules:
    - test.doc_module
    - lib.some_lib
```

## Add additional content

You can add custom content pages to your documentation site by creating Markdown (`.md`) files and referencing them in
the `additionalContent` section of your configuration.

### Example custom content file

Markdown

```
// <title> must match the title property configured in chromia.yml at docs:title

# Dapp <title>

// Content

// <module-1> should be replaced with the name of targeted module

# Module <module-1>

// Content

## Sub-titles are allowed

// Content

# Module <module-2>

// Content
```

## Customize styling

You can customize the look and feel of your documentation site by creating CSS files and referencing them in the
`customStyleSheets` section of your configuration.

### Example custom stylesheet

CSS

```
:root {
  --primary-color: #4a86e8;
  --secondary-color: #34a853;
  --text-color: #333333;
  --background-color: #e0c7f6;
  --code-background: #a2dbf7;
}

.navbar {
  background-color: var(--primary-color);
}

.sidebar {
  border-right: 1px solid #e16565;
}
```

### Add custom assets

You can include custom assets such as logos, favicons, and other images by placing them in a directory (e.g.,
`docs-assets`) and referencing them in the `customAssets` section of your configuration. If you want to replace any of
the default images or logos, this can be achieved by simply adding your own image file and naming it the same as the one
you would like to replace.

## Add additional modules

You can specify additional modules to be included during documentation generation using the `additionalModules`
configuration in your `chromia.yml` file. This is particularly useful for:

* Including test modules that contain usage examples
* Adding library modules that aren't part of the main module but should be documented
* Ensuring comprehensive API documentation by including supporting modules

### Configuration example

YAML

```
docs:
  # Other configuration options...
  additionalModules:
    - test.doc_module
    - test.examples
    - lib.common_utils
```

### Usage notes

* Each module should be specified with its full path (e.g., `test.module_name` or `lib.module_name`)
* Test modules can be valuable for documentation as they often contain practical usage examples
* You can organize your test modules specifically for documentation purposes (e.g., creating a `test.doc_examples`
  module)

## Troubleshooting

### Navigation bar not showing

If you cannot view the navigation bar and you haven't added any custom styling that would cause this, it is most likely
because you are not running the site on a web server. Two quick ways of running it on a server would be:

1. Using Docker

Terminal

```
docker run -dit --name my-docs-site -p 8080:80 -v "$PWD":/usr/local/apache2/htdocs/ httpd:2.4
```

2. Using Node.js

Terminal

```
npm install http-server
npx http-server
```

### Custom styling not applied

If your custom styles are not being applied:

* Check that the CSS file is correctly referenced in your `chromia.yml`
* Verify that the CSS selectors match the elements in the generated HTML
* Inspect the generated HTML to understand the structure and class names

[View this page on docs.chromia.com](https://docs.chromia.com/build/cli/generating-doc-site/)Content mirrored from the live docs
