Skip to content

Modifying content on this site

You have two options for editing content: directly in your browser using GitHub, or from your local work environment using a Git-based workflow.

Notes on content additions

Sections: Generally, content additions should fit somewhere within the existing top-level and second-level sections (like Background, or Kubernetes). Try not to introduce a new top-level or second-level section.

Text: Write your Markdown text in such a way that each sentence in a paragraph has its own line, and is followed immediately by a newline character with no spaces in between. This facilitates the review of your change, and it also helps you notice long run-on sentences as you write.

Headings: Keep headings concise, under 80 characters.

Screenshots: If you are contributing a change that contains screenshots from Cleura Cloud Management Panel, they should have a resolution of 1920×1080 pixels (1080p). If your screen has a larger resolution, use Firefox Responsive Design Mode or Chrome/Chromium Device Mode to configure your browser with 1080p.

Screenshots should be added to a directory named assets, located in the same directory as the Markdown file you are adding or editing.

CLI screen dumps: If you are contributing a change that contains a screen dump from the openstack command-line client, please limit its width to 100 characters. You can do this by setting the following environment variable in your terminal, before you start working on your change.

export CLIFF_MAX_TERM_WIDTH=100

Renamed sources: If you rename an existing Markdown source, the path of the rendered page’s URI will change. In this case, be sure to define a redirect from the old URI to the new one, by adding an entry to the plugins.redirect.redirect_maps dictionary in the mkdocs.yml configuration file.

Modifying content from your browser

Every page on this site has an Edit button (). If you click it, it’ll take you straight to the corresponding source page in GitHub. Then, you can follow GitHub’s documentation on how to propose changes to another user’s repository.

Modifying content using Git

The Git repository for this site lives on GitHub. You can fork that repository, make the proposed changes in your fork, and then send us a standard GitHub pull request.

For this purpose, use git in combination with either GitHub’s web interface, or the gh command-line interface (CLI).

First, create a fork of the documentation repository:

Open our GitHub repo and click the Fork button. When you create your new fork, it’s fine to leave the Copy the main branch only option enabled.

Then, proceed to create a new local checkout of your fork: 

git clone git@github.com:<yourusername>/<your-repo-fork> cleura cloud-docs
cd cleura cloud-docs


gh repo fork --clone https://github.com/citynetwork/docs -- cleura cloud-docs
cd cleura cloud-docs

Next, create a local topic branch and make your modifications:

git checkout -b <your-topic-branch-name>
# edit your files
git add <files-to-add>
git commit

Please see our notes on commit messages.

Finally, create a pull request (PR) from your changes:

Run the following git command (assuming origin is the remote that points to your fork): 

git push origin <your-topic-branch-name>
Then, open your browser to the URL suggested by the git push command, and proceed to create a pull request.

gh pr create --fill

Monitoring changes as you edit

To see your changes as you work on them, you can use tox. Having created a topic branch with your modifications, run:

cd cleura cloud-docs
git checkout <your-topic-branch-name>
tox -e serve

A local copy of the documentation will then run on your local machine and be accessible from http://localhost:8000 in your browser.

When planning to make several changes in rapid succession, you may want to speed up site rendering after each change. You may do so by disabling a plugin that checks all links (including external links) for accessibility:

cd cleura cloud-docs
export DOCS_ENABLE_HTMLPROOFER=false
tox -e serve

Commit messages

When you submit a change, you will need to provide a commit message, which is very nearly as important as the change itself. Excellent guides on what constitutes a good commit message are available from Tim Pope and Colleen Murphy.

In addition, we have adopted the Conventional Commits style for commit message subjects. Please make sure that your commit message starts with one of the following prefixes:

  • feat: denotes a content addition, such as adding documentation for some Cleura Cloud functionality that was not included in the documentation before.
  • fix: denotes a content correction, such as fixing a documentation bug.
  • build: denotes a change to the build process, such as an improvement to a CI check.
  • chore: denotes a minor change that is neither a feature, nor a fix, nor a build improvement, such as when you edit the .mailmap file.
  • docs: denotes a change to the documention for this site, such as an update to the README.md file.