Repository files navigation

This is aHugo project with a theme calledHextra added as a module.

• Developers Hub
• Developers Documentation
• Reference Environnement Variables
• Guides and Tutorials

• Beautiful Design - Inspired by Nextra, Hextra utilizes Tailwind CSS to offer a modern design that makes your site look outstanding.
• Responsive Layout and Dark Mode - It looks great on all devices, from mobile, tablet to desktop. Dark mode is also supported to accomodate various lighting conditions.
• Fast and Lightweight - Powered by Hugo, a lightning-fast static-site generator housed in a single binary file, Hextra keeps its footprint minimal. No Javascript or Node.js are needed to use it.
• Full-text Search - Built-in offline full-text search powered by FlexSearch, no additional configuration required.
• Battery-included - Markdown, syntax highlighting, LaTeX math formulae, diagrams and Shortcodes elements to enhance your content. Table of contents, breadcumbs, pagination, sidebar navigation and more are all automatically generated.
• Multi-language and SEO Ready - Multi-language sites made easy with Hugo's multilingual mode. Out-of-the-box support is included for SEO tags, Open Graph, and Twitter Cards.

To begin your journey with the Clever Cloud Documentation, you need to clone this repo.

Check your Go version, it need to be above go1.21.1.

Eitherinstall Hugo globally in your system or put itsexecutable in the projet's root.

To run the site locally, there is a server built in Hugo you can summon with:hugo server.A bunch of options are available:

 -b, --baseURL string         hostname and path to the root  -D, --buildDrafts            include content marked as draft      --cacheDir string        filesystem path to cache directory      --cleanDestinationDir    remove files from destination not foundin static directories  -c, --contentDir string      filesystem path to content directory      --disableFastRender      enables full re-renders on changes

Hugo refreshes the site as you modify the files, you can keep the server running with no need to restart.

There is no need to build before submitting your Pull Request or before deploying.

The theme used here is calledHextra.

Theclevercloud-deploy-script.sh script runs the compilation with the right options and serves the content of the public folder.

This is why the Clever Cloud application running this app needs to have a webroot serving/public/.

Follow these instructions to contribute to the doc.

1. Clone this repo:git clone git@github.com:CleverCloud/documentation.git
2. Go to the repo root:cd documentation
3. Start the theme module:hugo mod get github.com/imfing/hextra (optional, but do it if you encounter an error on step 4, to update the theme)
4. Runhugo server

Local site is displayed onhttp://localhost:1313

Hugo usesGoldmak, a Markdown parser written in Go, compliant with CommonMark 0.30(seethe specification here).

Therefore, for better readability and maintaining, all markdown files for this project are linted withhttps://github.com/DavidAnson/markdownlint-cli2.We strongly recommend that you follow the validation rules described here:https://github.com/DavidAnson/markdownlint#rules--aliases.

This linter can be downloaded and run locally, or used via VSCode:

• https://github.com/DavidAnson/vscode-markdownlint for VSCode
• https://github.com/DavidAnson/markdownlint-cli2 as a NPM package

Ignored markdown files are listed in the.markdownlintignore.Ignored specifications, such as some HTML tag of Web Components, are configured in the.markdownlint.jsoncEditorial checks withVale.sh. Install Vale on your machine or as a VSCode extension if you want to run checks before submitting your PR. This project is already configured to use it.

Runhugo new content guides/<framework>.md. Hugo generates a new file from a guide template (stored in/archetypes).

In this new guide file's metadata, setdraft: true to publish it.

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

Whenever possible, the famous "Bugs fixes and improvements" should be avoided.

The filename is not very important for the Hugo build and publication process, but it will serve as a slug for the URL. Ideally, it can start with the date inISO 8601 format and the title in Kebab case. This naming convention allow the files to be sorted easily in any editor.

The format is a markdown file with a.md extention:

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:

• title (required)

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

• date (recommended)

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

• description (recommended)

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

• tags (recommended)

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

• category (optional)

  • The category is used here to add a "new" label on the changelog homepage when a specific entry is a new feature that should be highlighted visually. The value must benew, and nothing else.

• authors (optional)

  • 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 a the parameter?size=40 for reducing the image size (recommended for performance). The values are all of<string> type.

• excludeSearch (recommended)

  • Indicates whether the changelog will be indexed in search. It can be activated for a post if deemed necessary. The values to be set are eithertrue orfalse

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

Adding an image can be useful for highlighting a change of interface, for example.You can achieve this by using a shortcode, which is a simple snippet inside the content files, calling a built-in or custom templates.The shortcode we are using here isfigure, as show below. Then move your image in the/images/changelog/your-image.jpg folder of this project.

The image size can be modified and adapted using thewidth andheight parameters.

Example :

{{<figuresrc="/images/changelog/console-new-ip-par.png"caption="The new IP shown in the console"width="800px">}}

Partials are reusable content you can include in several pages. To use this feature:

1. Create a new partial in/layouts/shortcodes/content
2. Add it to the relevant pages like this:{{% content/your-partial %}}