Repository files navigation

This project is based onHugo and usesHextra 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:

• Complete Markdown support
• Complete shortcodes set
• Diagrams
• LaTeX math formulae
• Syntax highlighting

• Home page
• Documentation
• API Documentation
• Guides and Tutorials
• Reference Clever Tools CLI
• Reference Environment Variables
• Clever Cloud Platform Changelog

To begin your journey with the Clever Cloud Documentation, you need Hugo. You can:

• Install it globally on your system
• Get itsbinary and put it in the project's root

Once your system is set up, clone this repository:

git clone https://github.com/CleverCloud/documentation

Then:

1. Go to the documentation folder:cd documentation
2. Runhugo server to build and start the local server

Local site is available onhttp://localhost:1313, it refreshes as you modify the files, you can keep the server running with no need to restart.Findserver command options in theHugo documentation.

The site is configured for Clever Cloud hosting with thestatic 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 routeCC_WEBROOT="public"CC_STATIC_AUTOBUILD_OUTDIR="public/developers"# Declare the location of the 404 custom pageSERVER_ERROR_PAGE_404="developers/404.html"

You can contribute bycreating an issue orsubmitting a pull request. If you use AI tools or LLMs, you'll find specific instructions for them:

• AI tools and LLMs instructions
• Claude Code guidance
• Contributing guidelines

Clever Cloud documentation is also available following thellms.txt specification.

To generates a file from a template (in/archetypes), run one of the following Hugo commands:

hugo new content guides/<framework>.mdhugo new content/doc/administrate/<feature>.mdhugo new content --kind applications doc/applications/<runtime>.md

In new page/guide front matter,draft is set totrue to prevent it from being mistakenly published.

For any significant change to the platform (updates, new features, etc.) a new entry is created in thecontent/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)

  • The type of content layout to apply. The value is a<string>, set it todocs except in changelog.

• weight (optional)

  • The weight of the content, used to order the sidebar. The value is an<integer>, default is0.

• linkTitle (optional)

  • The title of the content displayed in the sidebar. The value is a<string>, default is thetitle value.

• title (required)

  • The title displayed in the main heading. The value is a<string>.

• description (recommended)

  • The description displayed in meta-description for SEO purposes. The value is a<string>.

• excludeSearch (optional)

  • Indicates whether the page should be indexed in search. Default isfalse, we recommend setting it totrue for changelog entries.

• aliases (optional)

  • Aliases redirects the user to the right page. The value is a list of<string>, each string being a path to redirect from, relative to the base URL (without the/developer, for example:/doc/docker).

• comments (optional)

  • Whether to show the feedback block or not. The value is a<boolean>, default istrue.

• draft (optional)

  • Whether the page is a draft or not. The value is a<boolean>, default isfalse. If set totrue, the page is not built except if you use the--buildDrafts flag.

• keywords (optional)

  • Keywords are used for SEO purposes. The value is a list of<string>, each string being a keyword.

• tags (recommended)

  • Tags are recommended only in Changelog for easy product identification. They are written in lowercase and, if possible, use the same spelling throughout the posts. The value is a list of<string>.

• authors (mostly used in changelog)

  • Can be set to showcase the people behind the product. Authors are defined with aname,link for their Github or any other social network, and animage for the profile picture. The profile picture can be set with the GitHub avatar with a link likehttps://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)

  • The date that will be displayed in the post. The value is a string in ISO 8601 likeyyyy-mm-dd.

For example, a changelog entry front matter could look like this:

---title:Redis updated to v7.2.4description:Redis has been updated to v7.2.4 mostly to prevent security issuesdate:2024-01-11tags:  -redisauthors:  -name:BlackYouplink:https://github.com/BlackYoupimage:https://github.com/BlackYoup.png?size=40excludeSearch:true---

Adding an image can be useful to highlight an interface change, for example. Use such markdown syntax for that:

![Alt text](/images/your-image.jpg"Title of the image")

If needed, you can also usethefigure 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">}}

• Learn more about Hugo shortcodes

You can include shared content in several pages. To use this feature:

1. Create a new markdown file in/shared
2. Add it to the relevant pages with:{{% content "your-partial" %}}

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 thedata/tooltips.toml file. Once defined, tooltips automatically display when users hover over associated terms in the documentation.

Hugo usesGoldmark, a Markdown parser written in Go, compliant withCommonMark 0.30. Therefore, for better readability and maintainability, all markdown files for this project are linted withmarkdownlint-cli2. We strongly recommend that you follow the validation rules describedhere.

This linter can be downloaded and run locally, or used via Visual Studio Code:

• https://github.com/DavidAnson/vscode-markdownlint for Visual Studio Code
• https://github.com/DavidAnson/markdownlint-cli2 as anpm package

Ignored 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 usesVale.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.