Skip to main content

Generating and Customizing Documentation Sites for Rell Projects

This guide 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 comments in your code. See: RellDoc Documentation
  • Custom content pages that you can add
  • Customizable styling and branding

Generating a Documentation Site​

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

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.

To view the navigation bar, the generated site needs to run on a web server. See:

Navigation bar not showing

Configuring Documentation Generation​

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

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

Adding 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​

// <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

Customizing 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​

: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;
}

Adding 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.

Troubleshooting​

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
docker run -dit --name my-docs-site -p 8080:80 -v "$PWD":/usr/local/apache2/htdocs/ httpd:2.4
  1. Using Node.js
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