Writing Docs

This document contains guidelines for contributing changes to the Ent documentation website.

The Ent documentation website is generated from the project’s main GitHub repo.

Follow this short guide to contribute documentation improvements and additions:

Setting Up

1. Fork and clone locally the main repository.

2. The documentation site uses Docusaurus. To run it you will need Node.js installed.

3. Install the dependencies:

  1. cd doc/website && npm install

4. Run the website in development mode:

  1. cd doc/website && npm start

5. Open you browser at http://localhost:3000.

General Guidelines

  • Documentation files are located in doc/md, they are Markdown-formatted with “front-matter” style annotations at the top. Read more about Docusaurus’s document format.
  • Ent uses Golang CommitMessage formats to keep the repository’s history nice and readable. As such, please use a commit message such as:
  1. doc/md: adding a guide on contribution of docs to ent

Adding New Documents

1. Add a new Markdown file in the doc/md directory, for example doc/md/writing-docs.md.

2. The file should be formatted as such:

  1. ---
  2. id: writing-docs
  3. title: Writing Docs
  4. ---
  5. ...

Where id should be a unique identifier for the document, should be the same as the filename without the .md suffix, and title is the title of the document as it will appear in the page itself and any navigation element on the site.

3. If you want the page to appear in the documentation website’s sidebar, add its id to website/sidebars.js, for example:

  1. {
  2.       type: 'category',
  3.       label: 'Misc',
  4.       items: [
  5.         'templates',
  6.         'graphql',
  7.         'sql-integration',
  8.         'testing',
  9.         'faq',
  10.         'generating-ent-schemas',
  11.         'feature-flags',
  12.         'translations',
  13.         'contributors',
  14. +       'writing-docs',
  15.         'slack'
  16.       ],
  17.       collapsed: false,
  18.     },