This project is based on Hugo and uses Hextra theme. It provides a great design, a responsive layout, dark mode support, full-text search. It’s lightweight, fast, and SEO-ready, with many built-in features:
To begin your journey with the Clever Cloud Documentation, you need Hugo. You can:
Once your system is set up, clone this repository:
git clone https://github.com/CleverCloud/documentation
Then:
cd documentationhugo server to build and start the local serverLocal site is available on http://localhost:1313, it refreshes as you modify the files, you can keep the server running with no need to restart.
Find server command options in the Hugo documentation.
The site is configured for Clever Cloud hosting with the static runtime and these required environment variables:
# Declare what's the web server root, where to build the documentation
# You must have a `/developers` at the end of your application's route
CC_WEBROOT="public"
CC_STATIC_AUTOBUILD_OUTDIR="public/developers"
# Declare the location of the 404 custom page
SERVER_ERROR_PAGE_404="developers/404.html"
[!TIP]
You can set the Hugo version withCC_HUGO_VERSIONwith a value like0.161
You can contribute by creating an issue or submitting a pull request. If you use AI tools or LLMs, you’ll find specific instructions for them:
Clever Cloud documentation is also available following the llms.txt specification.
To generates a file from a template (in /archetypes), run one of the following Hugo commands:
hugo new content guides/<framework>.md
hugo new content/doc/administrate/<feature>.md
hugo new content --kind applications doc/applications/<runtime>.md
In new page/guide front matter, draft is set to true to prevent it from being mistakenly published.
[!TIP]
Usehugo server --buildDraftscommand to preview drafts locally
For any significant change to the platform (updates, new features, etc.) a new entry is created in the content/changelog folder.
Several entries can be made per day, it’s not a problem. Each entry should provide clear, straightforward information on the essentials. If you find yourself writing an enormous amount of content, this may not be the right approach. However, you can always add a little charm to your changelog, but it’s a tricky business, requiring careful, well-placed word choice.
The filename format is a markdown file with a .md extension:
yyyy-mm-dd-your-title.md
Hugo uses front matter to enrich posts with metadata. Front matter allows you to keep metadata attached to an instance of a content type—i.e., embedded inside a content file. We use the following Front matter variables:
type (optional)
<string>, set it to docs except in changelog.weight (optional)
<integer>, default is 0.linkTitle (optional)
<string>, default is the title value.title (required)
<string>.description (recommended)
<string>.excludeSearch (optional)
false, we recommend setting it to true for changelog entries.aliases (optional)
<string>, each string being a path to redirect from, relative to the base URL (without the /developer, for example: /doc/docker).comments (optional)
<boolean>, default is true.draft (optional)
<boolean>, default is false. If set to true, the page is not built except if you use the --buildDrafts flag.keywords (optional)
<string>, each string being a keyword.tags (recommended)
<string>.authors (mostly used in changelog)
name, link for their Github or any other social network, and an image for the profile picture. The profile picture can be set with the GitHub avatar with a link like https://github.com/BlackYoup.png and the parameter ?size=40 for reducing the image size (recommended for performance). The values are all of <string> type.date (mostly used in changelog)
yyyy-mm-dd.For example, a changelog entry front matter could look like this:
---
title: Redis updated to v7.2.4
description: Redis has been updated to v7.2.4 mostly to prevent security issues
date: 2024-01-11
tags:
- redis
authors:
- name: BlackYoup
link: https://github.com/BlackYoup
image: https://github.com/BlackYoup.png?size=40
excludeSearch: true
---
Adding an image can be useful to highlight an interface change, for example. Use such markdown syntax for that:
If needed, you can also use the figure shortcode to add attributes such as a width limit:
{{< figure src="/developers/images/your-image.jpg" alt="Alt text" title="Title of the image" width="800px">}}
You can include shared content in several pages. To use this feature:
/shared{{% content "your-partial" %}}[!TIP]
If you need to include a shared content including shortcodes, use{{% content-raw "your-partial" %}}instead. Don’t include headings (starting with#) in it as they won’t be rendered in the page Table of Contents (ToC).
Tooltips are useful to provide additional information on terms or acronyms that may not be familiar to all readers. They help improve the accessibility and comprehension of your documentation without cluttering the main text.
To create a tooltip, add the term and its associated tooltip definition in the data/tooltips.toml file. Once defined, tooltips automatically display when users hover over associated terms in the documentation.
Hugo uses Goldmark, a Markdown parser written in Go, compliant with CommonMark 0.30. Therefore, for better readability and maintainability, all markdown files for this project are linted with markdownlint-cli2. We strongly recommend that you follow the validation rules described here.
This linter can be downloaded and run locally, or used via Visual Studio Code:
npm packageIgnored markdown files are listed in the .markdownlintignore.
Ignored specifications, such as some HTML tag of Web Components, are configured in the .markdownlint.jsonc
This project uses Vale.sh to run editorial checks on the documentation. Install Vale on your machine or as an IDE extension if you want to run checks. This project is already configured to use it on pull requests.