diff --git a/.cursorrules b/.cursorrules deleted file mode 120000 index 02dd13412..000000000 --- a/.cursorrules +++ /dev/null @@ -1 +0,0 @@ -.github/copilot-instructions.md \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/content-suggestion.yaml b/.github/ISSUE_TEMPLATE/content-suggestion.yaml index f5199ec17..9a71ba68a 100644 --- a/.github/ISSUE_TEMPLATE/content-suggestion.yaml +++ b/.github/ISSUE_TEMPLATE/content-suggestion.yaml @@ -1,7 +1,7 @@ name: ๐Ÿ“ Content and guide suggestion -description: Suggest new documentation content, guides +description: Suggest new documentation content or a deployment guide title: "Content: " -labels: ["documentation", "enhancement"] +labels: ["enhancement"] body: - type: markdown attributes: @@ -16,9 +16,9 @@ body: description: "Have you checked if this content already exists?" options: - label: I have searched existing [documentation](https://www.clever.cloud/developers/) to verify this content doesn't already exist + required: true - label: I have checked for existing [issues](https://github.com/CleverCloud/documentation/issues) for this request - validations: - required: true + required: true - type: dropdown id: content-type @@ -53,7 +53,7 @@ body: id: framework-details attributes: label: "Technical details (for framework guides)" - description: "If it's a framework guide: name, version, specific challenges, etc." + description: "For a framework guide, provide its name, version and any deployment-specific requirements" placeholder: "Framework: Laravel 10, challenges: queue configuration with Redis, special dependencies..." - type: textarea diff --git a/.github/ISSUE_TEMPLATE/problem-report.yaml b/.github/ISSUE_TEMPLATE/problem-report.yaml index 82b5de0b4..84009ce4b 100644 --- a/.github/ISSUE_TEMPLATE/problem-report.yaml +++ b/.github/ISSUE_TEMPLATE/problem-report.yaml @@ -1,7 +1,7 @@ name: โš ๏ธ Report a problem description: Report an error, technical issue, UX problem, or request clarification title: "Issue: " -labels: ["documentation", "bug"] +labels: ["bug"] body: - type: markdown attributes: @@ -19,7 +19,7 @@ body: options: - Clarification request (unclear or incomplete information) - Documentation error (incorrect information, broken link, etc.) - - Technical site issue (Hugo build, shortcodes, functionality) + - Site or repository issue (Hugo, CI, shortcodes, rendering) - UX/design problem (accessibility, navigation, responsive) - Other problem validations: @@ -28,11 +28,11 @@ body: - type: textarea id: page-urls attributes: - label: "Affected page(s)" - description: "URLs of the documentation pages with the problem (one per line)" + label: "Affected page or file" + description: "Provide the affected documentation URL or repository path, one per line" placeholder: | https://www.clever.cloud/developers/... - https://www.clever.cloud/developers/... + .github/workflows/... validations: required: true diff --git a/.github/ISSUE_TEMPLATE/zzz-other.yaml b/.github/ISSUE_TEMPLATE/zzz-other.yaml index 1030139cc..a17e0be26 100644 --- a/.github/ISSUE_TEMPLATE/zzz-other.yaml +++ b/.github/ISSUE_TEMPLATE/zzz-other.yaml @@ -1,7 +1,6 @@ name: โ“ Other request description: For requests that don't fit into other categories title: "Other: " -labels: ["documentation"] body: - type: markdown attributes: @@ -19,9 +18,9 @@ body: description: "Have you checked the appropriate resources?" options: - label: I have checked that this request doesn't fit into other issue templates + required: true - label: I have searched for existing [issues](https://github.com/CleverCloud/documentation/issues) - validations: - required: true + required: true - type: textarea id: issue-description diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 839f8222b..000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,294 +0,0 @@ -# AI Content Creation Rules for Clever Cloud Documentation - -This document provides comprehensive guidance for AI systems on creating high-quality content for Clever Cloud's documentation platform, including technical documentation, guides, and changelog entries. - -## Development Environment - -This is a Hugo-based documentation site using the Hextra theme. - -### Hugo Development Commands -- **Build and serve locally**: `hugo server` (site available at http://localhost:1313) -- **Build for production**: `hugo` (outputs to `public/developers/`) -- **Preview with drafts**: `hugo server --buildDrafts` -- **Generate new content**: - - `hugo new content guides/.md` - - `hugo new content/doc/administrate/.md` - - `hugo new content --kind applications doc/applications/.md` -- **Update CLI reference**: `./update-cli-reference.sh` - -### Project Structure -- **Content organization**: `/content/` contains all documentation: - - `doc/` - Main documentation (applications, addons, CLI, etc.) - - `guides/` - Framework-specific tutorials and guides - - `changelog/` - Platform updates and announcements - - `api/` - API documentation - - `postmortem/` - Incident reports -- **Shared content**: `/shared/` contains reusable content blocks -- **Data files**: `/data/` contains structured data (runtime versions, tooltips, etc.) -- **Static assets**: `/static/` for images, fonts, and other assets - -### Content Management System -- Uses Hugo front matter with fields: `type`, `weight`, `linkTitle`, `description`, `excludeSearch`, `aliases`, `draft`, `tags`, `authors` -- New pages have `draft: true` by default - change to `false` to publish -- Tooltips defined in `data/tooltips.toml` and auto-display on hover -- **Quality enforcement**: - - Markdown linting via markdownlint-cli2 (config: `.markdownlintignore`, `.markdownlint.jsonc`) - - Editorial checks via Vale.sh (config: `.vale.ini`) - - Vocabulary in `.github/styles/config/vocabularies/Doc/accept.txt` - -## Content Types Overview - -### 1. Technical Documentation (`/content/doc/`) -Formal reference material for platform features, APIs, and configurations. -- **Style**: Professional, precise, instructional -- **Structure**: Hierarchical with clear sections -- **Purpose**: Enable users to accomplish specific tasks - -### 2. Guides & Tutorials (`/content/guides/`) -Step-by-step instructions for implementing specific technologies or frameworks. -- **Style**: Educational, conversational but focused -- **Structure**: Progressive steps with examples -- **Purpose**: Guide users through complete implementation - -### 3. Changelog Entries (`/content/changelog/`) -Technical blog-style posts announcing platform updates and new features. -- **Style**: Engaging, informative, personality allowed -- **Structure**: Context โ†’ announcement โ†’ practical examples โ†’ links -- **Purpose**: Inform users about platform evolution - -## Writing Style Guidelines - -### Universal Rules (All Content Types) - -#### Language Standards -- Use **second person** ("you") to address readers directly -- Write in **active voice** - avoid passive constructions -- Use **British spelling** for "organisation" not "organization" -- **Avoid first-person pronouns**: I, me, my, we, us, our, let's -- Keep sentences **short and clear** (max 25 words when possible) -- **No jargon** - explain technical terms when first introduced - -#### Prohibited Phrases -- Placeholder phrases: "please note", "at this time", "it should be noted" -- Overconfident claims: "simply", "just", "easily", "quickly", "obviously" -- Time-dependent promises: "soon", "in the future", "coming next month" -- Over-politeness: excessive use of "please" - -#### Required Elements -- **Don't assume prior knowledge** - over-explain rather than under-explain -- Address the reader's **specific use case** and context -- Provide **concrete examples** with real commands, code, or configurations -- Include **relevant links** to related documentation - -### Documentation-Specific Rules - -#### Structure Requirements -```yaml ---- -type: docs -linkTitle: Short Title -title: Full Page Title -description: SEO-friendly description explaining what users will learn -aliases: -- /old/url/path ---- -``` - -#### Content Organization -- **Overview section** - Brief explanation of what the technology/feature is -- **Create/Setup section** - How to get started -- **Configure section** - Detailed configuration options -- **Advanced features** - Optional capabilities -- **Examples and references** - Practical implementations - -#### Technical Specifications -- Always specify **current versions** of software/tools -- Include **environment variables** with exact names and examples -- Provide **command-line examples** with proper syntax -- Use **callouts for important information**: - ```markdown - > [!NOTE] Context about new features - > [!TIP] Helpful suggestions - > [!WARNING] Important considerations - ``` - -### Guide-Specific Rules - -#### Engaging Introduction -- Start with **hero subtitle shortcode** explaining the framework/tool benefits -- Use **hextra shortcodes** for enhanced presentation: - ```markdown - {{< hextra/hero-subtitle >}} - Brief engaging description of what users will build - {{< /hextra/hero-subtitle >}} - ``` - -#### Step-by-Step Structure -- Use **steps shortcode** for sequential instructions: - ```markdown - {{% steps %}} - ### Step Title - Content and commands - {{% /steps %}} - ``` - -- Include **tab groups** for different package managers/approaches: - ```markdown - {{< tabs items="npm,yarn,pnpm" >}} - {{< tab >}}Content for npm{{< /tab >}} - {{< tab >}}Content for yarn{{< /tab >}} - {{< /tabs >}} - ``` - -#### Learning Resources -- End with **cards section** linking to related documentation: - ```markdown - {{< cards >}} - {{< card link="/path" title="Title" subtitle="Description" icon="icon-name" >}} - {{< /cards >}} - ``` - -### Changelog-Specific Rules - -#### Front Matter Format -```yaml ---- -title: Descriptive title about the update/feature -description: Brief one-line summary -date: YYYY-MM-DD -tags: - - relevant-product-tags -authors: - - name: Full Name - link: https://github.com/username - image: https://github.com/username.png?size=40 -excludeSearch: true ---- -``` - -#### Writing Style for Changelog -- **More personality allowed** - can be engaging and slightly conversational -- **Lead with impact** - explain why this matters to users -- **Provide context** - link to upstream releases, related changes -- **Include practical examples** - show users exactly how to use new features -- **Multiple entries per day acceptable** - don't batch unrelated updates - -#### Content Flow Pattern -1. **Context paragraph** - What changed and why it matters -2. **Technical details** - Versions, new features, improvements -3. **Implementation examples** - Concrete commands or configuration -4. **Related links** - Documentation, examples, community resources - -#### Command Examples in Changelog -Always show **complete command sequences**: -```bash -# Enable the feature -clever features enable operators - -# Check current version -clever keycloak version check yourKeycloakNameOrId - -# Update to latest -clever keycloak version update yourKeycloakNameOrId -``` - -## Technical Implementation Standards - -### Code Examples -- **Always complete and runnable** - no placeholder variables without explanation -- **Include setup context** - show what directory, prerequisites needed -- **Use realistic names** - avoid "foo", "bar", "example" -- **Show expected output** when helpful - -### Environment Variables -- **Exact variable names** with proper casing: `CC_NODE_BUILD_TOOL` -- **Show complete examples**: - ```bash - CC_WEBROOT="public" - CC_RUN_COMMAND="npm start" - ``` -- **Explain the impact** of each variable - -### File References -- **Absolute paths** when referencing project structure -- **Relative paths** when showing user actions: `./package.json` -- **Proper syntax highlighting** for code blocks - -## Content Quality Checklist - -### Before Publishing Documentation -- [ ] All commands tested and work as shown -- [ ] Environment variables verified with exact syntax -- [ ] Links point to correct, existing pages -- [ ] Examples use realistic project names and values -- [ ] No first-person pronouns (I, we, us, our) -- [ ] Short, clear sentences under 25 words -- [ ] Proper callouts for important information - -### Before Publishing Changelog -- [ ] Clear benefit/impact stated upfront -- [ ] Version numbers and dates accurate -- [ ] Complete command examples provided -- [ ] Author information included with GitHub avatar -- [ ] Tags relevant to affected products -- [ ] Links to documentation and examples working - -### Before Publishing Guides -- [ ] Step-by-step flow tested end-to-end -- [ ] All code examples complete and functional -- [ ] Prerequisites clearly stated -- [ ] Expected outcomes explained -- [ ] Hextra shortcodes used appropriately -- [ ] Learning resources section included - -## Shared Content Usage - -### Including Reusable Blocks -- Use `{{% content "filename" %}}` for basic shared content -- Use `{{% content-raw "filename" %}}` for content containing shortcodes -- Available shared blocks in `/shared/` directory include common procedures - -### Creating New Shared Content -- Extract **commonly repeated information** into `/shared/filename.md` -- **No headings** in shared content (breaks table of contents) -- Focus on **procedural steps** rather than context - -## Maintenance and Updates - -### Keeping Content Current -- **Version numbers** should reflect current platform state -- **Screenshots and UI references** need regular updates -- **External links** should be verified periodically -- **Deprecated features** should be clearly marked - -### Community Integration -- **Link to community discussions** for new features -- **Reference GitHub examples** when available -- **Encourage feedback** on experimental features -- **Update based on user reports** and common issues - -## Deployment Configuration - -The site is configured for Clever Cloud hosting with the `static` runtime and these required environment variables: -- `CC_WEBROOT="public"` -- `CC_STATIC_AUTOBUILD_OUTDIR="public/developers"` -- `SERVER_ERROR_PAGE_404="developers/404.html"` -- Optional: `CC_HUGO_VERSION="0.152"` to specify Hugo version (example value) - -## Quality Assurance Requirements - -### Build Verification -Always test changes with the `hugo` command before committing to ensure the build is functional. Fix any build errors immediately as they prevent deployment. Verify that all links, references, image paths, and shortcode syntax work correctly in the generated output. - -### File Standards -All files must end with a single blank line to comply with git standards and POSIX requirements. - -### Content Quality Standards -Minimise the use of bullet points and lists. Use them only when essential for clarity or information efficiency. -Structure each section with 2-4 well-developed paragraphs. Avoid single text blocks or overly fragmented content. -Aim for paragraphs of 3-6 lines for optimal readability. Each paragraph should contain a complete thought or concept. -Use descriptive section titles. Titles should create useful table of contents entries. -Organise information logically so each section forms a coherent, useful unit. -Ensure all necessary information is included in readable prose, not fragmented lists. - -This document ensures consistent, high-quality content across all Clever Cloud documentation while respecting the different styles appropriate for technical docs, educational guides, and announcement posts. diff --git a/.github/external-doc-issue.yml b/.github/external-doc-issue.yml index b22601341..f4620b6d1 100644 --- a/.github/external-doc-issue.yml +++ b/.github/external-doc-issue.yml @@ -1,18 +1,17 @@ --- -title: External doc update from PR {{ env.PR_NUMBER }} -labels: documentation +title: Update external documentation after PR {{ env.PR_NUMBER }} +labels: enhancement --- ## External documentation update needed -Update the external documentation: +Review the corresponding external documentation after these changes: - Author: @{{ payload.sender.login }} - PR: {{ env.PR_URL }} - Modified files: {{ env.CHANGED_FILES }} -Make a PR on one of these repositories: +Open a pull request in the relevant repository: - [Astro](https://github.com/withastro/docs) - - +- [Nuxt](https://github.com/nuxt/nuxt) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 478f756e9..9522ac4de 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,12 @@ -## ๐Ÿ“ What does this PR do? +## ๐Ÿ“ Summary -_Briefly describe your changes and why they are needed_ +Describe the changes and their purpose - -## ๐Ÿ”— Related Issue (if applicable) +## ๐Ÿ”— Related issue - Closes # - Related to # ---- - ## ๐Ÿงช Type of Change - [ ] โš ๏ธ Bug fix @@ -18,33 +15,9 @@ _Briefly describe your changes and why they are needed_ - [ ] โœจ New content/feature - [ ] ๐Ÿ”ง Technical/maintenance ---- - -## โœ… Quick Checklist - -- [ ] I have read the [contributing guidelines](https://github.com/CleverCloud/documentation/blob/main/CONTRIBUTING.md) -- [ ] The content is accurate and links work -- [ ] The site builds without errors - ---- - -## ๐Ÿ‘ฅ Reviewers - -@CleverCloud/reviewers - ---- - -
-๐Ÿ“‹ For major changes (click to expand) - -### Additional testing performed -_Describe any specific testing done for complex changes_ - -### Screenshots -_Add screenshots for visual/layout changes_ - -### Breaking changes -_List any breaking changes or migration notes_ - -
+## โœ… Validation +- [ ] Read the [contributing guidelines](https://github.com/CleverCloud/documentation/blob/main/CONTRIBUTING.md) +- [ ] Verify content accuracy and links +- [ ] Run relevant checks and builds +- [ ] Check the rendered result when the change affects layout or formatting diff --git a/.github/styles/Google/Anthropomorphism.yml b/.github/styles/Google/Anthropomorphism.yml new file mode 100644 index 000000000..36137a166 --- /dev/null +++ b/.github/styles/Google/Anthropomorphism.yml @@ -0,0 +1,12 @@ +extends: existence +message: "Don't attribute human qualities to software or hardware ('%s')." +link: https://developers.google.com/style/anthropomorphism +level: suggestion +ignorecase: true +# Limited to the two verbs the guide itself names. Broader lists (wants, knows, +# thinks) can't tell a software subject from a human one: on a 950-file corpus +# they produced 8 false positives ('the customer wants', 'your audience knows') +# for every 2 real ones. +tokens: + - sees + - tells diff --git a/.github/styles/Google/Colons.yml b/.github/styles/Google/Colons.yml index 4a027c307..98972b987 100644 --- a/.github/styles/Google/Colons.yml +++ b/.github/styles/Google/Colons.yml @@ -1,8 +1,13 @@ extends: existence message: "'%s' should be in lowercase." link: 'https://developers.google.com/style/colons' -nonword: true level: warning scope: sentence +# The match is the word itself, not ': X', and `nonword` is off. Both are +# required for a project Vocab to work: Vale compares accept.txt entries +# against the matched text, and `nonword: true` opts out of that entirely. +# So a proper noun after a colon can be exempted by adding it to accept.txt. +# The guide's other exemption, notice labels, is handled by the lookbehinds; +# headings are already excluded by `scope: sentence`. See issue #20. tokens: - - '(?}} + // are not Markdown, but markdownlint reads them as bare URLs. Wrapping the value in + // <> silences the rule and makes Go reject the URL, rendering href="#ZgotmplZ". + // Keep URLs bare in shortcode attributes. + "MD034": false, + "MD041": false, + "MD051": false, + "MD055": { + "style": "leading_and_trailing" + }, + "MD060": { + "style": "aligned" } -} \ No newline at end of file +} diff --git a/.markdownlintignore b/.markdownlintignore deleted file mode 100644 index ab4b6d49a..000000000 --- a/.markdownlintignore +++ /dev/null @@ -1,2 +0,0 @@ -/public/* -/resources diff --git a/.vale.ini b/.vale.ini index ebc876a2e..b39f99934 100644 --- a/.vale.ini +++ b/.vale.ini @@ -7,11 +7,11 @@ MinAlertLevel = suggestion Packages = Hugo, Google [*.md] -BasedOnStyles = Clever, Vale, Google, Guides +BasedOnStyles = Clever, Vale, Google Google.Headings = NO Vale.Terms = NO Google.Parens = NO Google.Ellipses = NO [*.xml] -Transform = docbook-xsl-snapshot/html/docbook.xsl \ No newline at end of file +Transform = docbook-xsl-snapshot/html/docbook.xsl diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..027829c95 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,209 @@ +# AGENTS.md + +This file provides repository-wide guidance to coding agents working on Clever Cloud documentation. Task-specific deployment-guide workflows live in `.agents/skills/`. + +## Common Development Commands + +### Hugo Site Development + +- **Install development dependencies**: `mise install` - Installs the tools declared in `mise.toml` +- **Local development**: `hugo server` - Serves site at with live reload +- **Build for production**: `hugo` - Outputs to `public/developers/` +- **Preview drafts**: `hugo server --buildDrafts` - Include draft content in local preview +- **Update CLI reference**: `./update-cli-reference.sh` - Fetches latest clever-tools documentation + +### Content Generation + +- **New guide**: `hugo new content guides/.md` +- **New documentation**: `hugo new content/doc/administrate/.md` +- **New application runtime**: `hugo new content --kind applications doc/applications/.md` + +## Project Architecture + +### Content Organization + +This is a Hugo-based documentation site using the Hextra theme with the following structure: + +- **`/content/`** - All documentation content: + - `doc/` - Main technical documentation (applications, addons, CLI, administration) + - `guides/` - Framework-specific tutorials and step-by-step guides + - `changelog/` - Platform updates and feature announcements + - `api/` - API reference documentation + - `postmortem/` - Incident reports and analysis +- **`/shared/`** - Reusable content blocks included via `{{% content "filename" %}}` shortcode +- **`/data/`** - Structured data files: + - `runtime_versions.yml` - Supported runtime versions and EOL status + - `tooltips.toml` - Tooltip definitions that auto-display on hover + - `icons.yaml`, `software_versions_shared_dedicated.yml` - Additional data +- **`/static/`** - Static assets (images, fonts, favicon, etc.) +- **`/layouts/`** - Hugo templates and shortcodes for content rendering + +### Content Types and Front Matter + +Content uses Hugo front matter with fields such as: + +- `type: docs` - Content layout type +- `weight` - Sidebar ordering (integer) +- `linkTitle` - Short title for sidebar navigation +- `description` - SEO meta description +- `keywords` - Array of SEO keywords +- `aliases` - Redirect paths for pages that previously existed at another URL; don't add aliases to a new page +- `draft: true` - Prevents publishing; remove this field when the page is ready instead of keeping `draft: false` +- `excludeSearch: true` - Excludes from search index (recommended for changelog) + +For changelog entries, also include: + +- `date: YYYY-MM-DD` - Publication date +- `tags` - Array of product tags (lowercase) +- `authors` - Array with `name`, `link`, `image` fields + +### Moving or Merging Content + +When a page moves to another URL, or when its content is merged into another page: + +- Always add the old URL to the destination page's `aliases`, so Hugo keeps serving a redirect +- Carry over every alias the removed page already declared; they must keep resolving +- Update internal links to target the new URL directly instead of relying on the redirect, especially in `shared/` blocks included by many pages +- Check each redirect in the build output before committing + +### Shared Content System + +- Include shared content: `{{% content "filename" %}}` +- Include shared content with shortcodes: `{{% content-raw "filename" %}}` +- Shared files should not contain headings (breaks ToC generation) + +## Quality Standards + +### Content Quality Requirements + +- Use second person ("you") addressing readers directly +- Write in active voice, avoid passive constructions +- Use `organisation` and `organisations`, rather than `organization` and `organizations`; this isn't a general British-spelling requirement +- Keep sentences under 25 words when possible +- Provide concrete examples with real commands and configurations +- Explain prerequisites and non-obvious behaviour, while keeping the main task path concise + +### Prohibited Elements + +- First-person pronouns: I, me, my, we, us, our, let's +- Placeholder phrases: "please note", "at this time", "it should be noted" +- Overconfident claims: "simply", "just", "easily", "quickly", "obviously" +- Time-dependent promises: "soon", "in the future", "coming next month" + +### Markdown and Editorial Standards + +- **Markdown linting**: Run `markdownlint-cli2 "**/*.md"` with config in `.markdownlint.jsonc` +- **Editorial checks**: Run Vale with `vale ` for style and terminology +- **Build verification**: Always test with `hugo` before committing +- **Structure**: Use 2-4 well-developed paragraphs per section, minimize bullet lists +- **Paragraphs**: Aim for 3-6 lines for optimal readability + +### Callouts + +- Prefer GitHub-style callouts with a concise title on the marker line, as supported by the theme: + + ```markdown + > [!NOTE] Current behaviour + > This information helps readers understand the current behaviour + + > [!WARNING] Back up your data + > Back up your application database before upgrading + ``` + +- Use the Hugo `{{< callout >}}` shortcode only when GitHub-style syntax can't provide the required rendering or behaviour +- Limit callouts to one or two per page + +### Commit Messages + +- For content updates, use `section(page): commit message`, for example: + - `addons(postgresql): document pg_partman support` + - `applications(nodejs): clarify pnpm configuration` + - `guides: add SvelteKit` for a new deployment guide +- For changelog entries, use `changelog: what you announce`. Name the product and its version, or the change itself, instead of starting with a verb: + - `changelog: Keycloak 26.7.3` + - `changelog: MySQL 8.0.46 and 8.4.10` + - `changelog: PostgreSQL 18 by default` + - `changelog: images updates, 2026W34` +- Commit a changelog entry with the documentation pages and data files it relies on, so an announcement never lands before the pages it links to +- For documentation structure, Hugo, deployment, CI, tooling, or dependency changes, use standard Conventional Commits, for example: + - `feat(hugo): add a shortcode for version tables` + - `fix(ci): run Vale on shared content` + - `refactor(layouts): simplify changelog rendering` + - `chore(deps): update the Hextra theme` +- Split content and structural changes into separate commits when possible +- Start the subject with a lowercase imperative verb, except for changelog entries + +### Code and Technical Examples + +- Always provide complete, runnable code examples +- Keep commands literally copyable: don't put shell-invalid placeholders or bracketed optional arguments in executable code blocks +- Show optional flags in separate examples or explain where to add them +- Use exact environment variable names: `CC_WEBROOT`, `CC_NODE_BUILD_TOOL`, etc. +- Include setup context and expected output when helpful +- Use realistic names instead of "foo", "bar", "example" +- Show complete command sequences in changelog entries +- Add code comments only when they explain non-obvious behaviour +- Don't add a full stop to a short standalone line made of one simple sentence, especially a single-line code comment, label, or concise list item. Use normal terminal punctuation for developed or multi-sentence prose, including list items. +- Don't hard-wrap prose with formatting-only line breaks that don't affect rendering; keep each paragraph on one logical line and rely on editor word wrap. +- Sort lists and tables alphabetically unless a functional or chronological order is more useful + +### Deployment Guides + +- Prefer one clear path that uses platform defaults and native features +- Follow every documented command from a fresh project and test every behaviour the guide promises +- Verify the default build and run configuration before documenting any scaling override +- Omit `-a` when the current directory is linked to only one application; use an application alias to disambiguate or link resources +- Follow the option style used by recent guides, including short Clever Tools options where established +- Place the standard `clever domain` and custom-domain example immediately after application creation +- Use `openssl rand -base64 32` when a guide needs a portable password-generation example and OpenSSL is already a prerequisite +- Make sure captured command output doesn't expose credentials, tokens, add-on environment values, or unrelated account data +- Validate public-storage claims with an unauthenticated request and persistence claims after a restart or rebuild +- Inspect generated HTML for tabs, code blocks, cards, links, and copyable commands; a successful Hugo build alone doesn't validate rendering +- Give `title` a descriptive, SEO-oriented value without repeating "Clever Cloud"; keep `linkTitle` short, usually the product name + +## Deployment Configuration + +The site is configured for Clever Cloud hosting with the `static` runtime and these required environment variables: + +- `CC_DISABLE_MISE="true"` +- `CC_WEBROOT="public"` +- `CC_STATIC_AUTOBUILD_OUTDIR="public/developers"` +- `SERVER_ERROR_PAGE_404="developers/404.html"` +- Optional: `CC_HUGO_VERSION="0.164"` to specify Hugo version (example value) + +`CC_DISABLE_MISE` prevents Clever Cloud from installing the local development dependencies because the platform manages the deployment tools directly. + +## Data Management + +Runtime versions and software compatibility information is maintained in `/data/runtime_versions.yml` and should be kept current with platform capabilities. The site generates various output formats including standard HTML and a special LLMS output format at `/llms.txt` for AI consumption. + +## Hugo Shortcodes and Features + +### Content Shortcodes + +- `{{% content "filename" %}}` - Include shared content from `/shared/` directory +- `{{% content-raw "filename" %}}` - Include shared content containing shortcodes +- `{{% steps %}}` - Create step-by-step instructions for guides +- `{{< tabs >}}` with named `{{< tab name="npm" >}}` children - Create tabbed content sections +- `{{< cards >}}` - Display card layouts for related resources +- `{{< callout >}}` - Create a callout only when GitHub-style syntax isn't sufficient +- `{{< hextra/hero-subtitle >}}` - Add engaging subtitles in guides + +### Hugo Content Types + +- **Documentation pages**: Use `type: docs` in front matter +- **Guides**: Use step-by-step structure, hero subtitles, and cards when they improve the guide +- **Changelog entries**: Include date, tags, and author information +- **API documentation**: Structured reference content + +### Hextra Theme Features + +- **Search**: Full-text search using FlexSearch +- **Dark mode**: Automatic theme switching +- **Responsive navigation**: Sidebar and mobile-friendly menus +- **Edit links**: Direct GitHub editing integration +- **Syntax highlighting**: Code block highlighting with copy functionality + +## File Standards + +All text files must end with a newline. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index f017e46fb..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,123 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Additional AI guidance is available in `.github/copilot-instructions.md` for comprehensive content creation rules. - -## Common Development Commands - -### Hugo Site Development -- **Local development**: `hugo server` - Serves site at http://localhost:1313 with live reload -- **Build for production**: `hugo` - Outputs to `public/developers/` -- **Preview drafts**: `hugo server --buildDrafts` - Include draft content in local preview -- **Update CLI reference**: `./update-cli-reference.sh` - Fetches latest clever-tools documentation - -### Content Generation -- **New guide**: `hugo new content guides/.md` -- **New documentation**: `hugo new content/doc/administrate/.md` -- **New application runtime**: `hugo new content --kind applications doc/applications/.md` - -## Project Architecture - -### Content Organization -This is a Hugo-based documentation site using the Hextra theme with the following structure: - -- **`/content/`** - All documentation content: - - `doc/` - Main technical documentation (applications, addons, CLI, administration) - - `guides/` - Framework-specific tutorials and step-by-step guides - - `changelog/` - Platform updates and feature announcements - - `api/` - API reference documentation - - `postmortem/` - Incident reports and analysis -- **`/shared/`** - Reusable content blocks included via `{{% content "filename" %}}` shortcode -- **`/data/`** - Structured data files: - - `runtime_versions.yml` - Supported runtime versions and EOL status - - `tooltips.toml` - Tooltip definitions that auto-display on hover - - `icons.yaml`, `software_versions_shared_dedicated.yml` - Additional data -- **`/static/`** - Static assets (images, fonts, favicon, etc.) -- **`/layouts/`** - Hugo templates and shortcodes for content rendering - -### Content Types and Front Matter -All content uses Hugo front matter with specific fields: -- `type: docs` - Content layout type -- `weight` - Sidebar ordering (integer) -- `linkTitle` - Short title for sidebar navigation -- `description` - SEO meta description -- `keywords` - Array of SEO keywords -- `aliases` - Array of redirect paths (relative to base URL) -- `draft: true` - Prevents publishing (change to `false` to publish) -- `excludeSearch: true` - Excludes from search index (recommended for changelog) - -For changelog entries, also include: -- `date: YYYY-MM-DD` - Publication date -- `tags` - Array of product tags (lowercase) -- `authors` - Array with `name`, `link`, `image` fields - -### Shared Content System -- Include shared content: `{{% content "filename" %}}` -- Include shared content with shortcodes: `{{% content-raw "filename" %}}` -- Shared files should not contain headings (breaks ToC generation) - -## Quality Standards - -### Content Quality Requirements -- Use second person ("you") addressing readers directly -- Write in active voice, avoid passive constructions -- Use British spelling: "organisation" not "organization" -- Keep sentences under 25 words when possible -- Provide concrete examples with real commands and configurations -- Over-explain rather than under-explain technical concepts - -### Prohibited Elements -- First-person pronouns: I, me, my, we, us, our, let's -- Placeholder phrases: "please note", "at this time", "it should be noted" -- Overconfident claims: "simply", "just", "easily", "quickly", "obviously" -- Time-dependent promises: "soon", "in the future", "coming next month" - -### Markdown and Editorial Standards -- **Markdown linting**: Uses markdownlint-cli2 with config in `.markdownlint.jsonc` -- **Editorial checks**: Uses Vale.sh for style and terminology -- **Build verification**: Always test with `hugo` command before committing -- **Structure**: Use 2-4 well-developed paragraphs per section, minimize bullet lists -- **Paragraphs**: Aim for 3-6 lines for optimal readability - -### Code and Technical Examples -- Always provide complete, runnable code examples -- Use exact environment variable names: `CC_WEBROOT`, `CC_NODE_BUILD_TOOL`, etc. -- Include setup context and expected output when helpful -- Use realistic names instead of "foo", "bar", "example" -- Show complete command sequences in changelog entries - -## Deployment Configuration -The site is configured for Clever Cloud hosting with the `static` runtime and these required environment variables: -- `CC_WEBROOT="public"` -- `CC_STATIC_AUTOBUILD_OUTDIR="public/developers"` -- `SERVER_ERROR_PAGE_404="developers/404.html"` -- Optional: `CC_HUGO_VERSION="0.152"` to specify Hugo version (example value) - -## Data Management -Runtime versions and software compatibility information is maintained in `/data/runtime_versions.yml` and should be kept current with platform capabilities. The site generates various output formats including standard HTML and a special LLMS output format at `/llms.txt` for AI consumption. - -## Hugo Shortcodes and Features - -### Content Shortcodes -- `{{% content "filename" %}}` - Include shared content from `/shared/` directory -- `{{% content-raw "filename" %}}` - Include shared content containing shortcodes -- `{{% steps %}}` - Create step-by-step instructions for guides -- `{{< tabs items="npm,yarn,pnpm" >}}` - Create tabbed content sections -- `{{< cards >}}` - Display card layouts for related resources -- `{{< callout >}}` - Create note, tip, warning callouts -- `{{< hextra/hero-subtitle >}}` - Add engaging subtitles in guides - -### Hugo Content Types -- **Documentation pages**: Use `type: docs` in front matter -- **Guides**: Use step-by-step structure with hero subtitles and cards -- **Changelog entries**: Include date, tags, and author information -- **API documentation**: Structured reference content - -### Hextra Theme Features -- **Search**: Full-text search using FlexSearch -- **Dark mode**: Automatic theme switching -- **Responsive navigation**: Sidebar and mobile-friendly menus -- **Edit links**: Direct GitHub editing integration -- **Syntax highlighting**: Code block highlighting with copy functionality - -## File Standards -All files must end with a single blank line to comply with git standards and POSIX requirements. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71c384682..30e56fa97 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,13 @@ # Contributing guidelines -This document provides explicit standards expected in Clever Cloud documentation. Inspiration and research for this document comes from the incredible [Awesome Code Review](https://github.com/joho/awesome-code-review) project. You'll find instructions for AI tools and LLMs: +This document provides explicit standards expected in Clever Cloud documentation. Inspiration and research for this document comes from the incredible [Awesome Code Review](https://github.com/joho/awesome-code-review) project. You'll find repository instructions for coding agents and LLMs: -- [AI tools and LLMs instructions](./.cursorrules) +- [Coding agent instructions](./AGENTS.md) ## Standards -Those are general standards to fulfill for every modification in this repository. +Those are general standards to fulfill for every modification in this repository ### ๐Ÿฏ Structure @@ -23,30 +23,58 @@ Follow the established structure in this doc. If you wish to propose changes to Follow these guidelines while writing new content. The goal is to help you write in a **clear, precise, and unambiguous language**. They're not meant to be a burden, but to help you deliver the best content possible. -Sources for quality content are currently being updated. +Sources for quality content are currently being updated #### ๐Ÿ‘ Do -- **Don't assume the user "knows better":** if you think something is obvious, it's not. Better over-explain than under-explain. -- **Use active voice:** passive voice can make it harder for the readers to figure out who's supposed to do something. -- **Use second person:** address the reader directly. -- **Keep it simple:** avoid jargon, complex sentences, and jokes. +- **Don't assume prior knowledge:** explain prerequisites and non-obvious behaviour without burying the main task path +- **Use active voice:** passive voice can make it harder for the readers to figure out who's supposed to do something +- **Use second person:** address the reader directly +- **Keep it simple:** avoid jargon, complex sentences, and jokes - **Keep it short:** keep the sentences short. Titles should be short and to the point. Keep longer content for the description metadata or the card subtitle. #### ๐Ÿ‘Ž Don't -- Placeholder phrases like _please note_ and _at this time_. -- Words and phrases that make promises or project plans and strategies: See [Writing timeless documentation](https://developers.google.com/style/timeless-documentation). -- Using phrases like _simply_, _It's that simple_, _It's easy_, or _quickly_ in a procedure. -- Over-politeness with the use of _please_: go straight to the point. +- Placeholder phrases like _please note_ and _at this time_ +- Words and phrases that make promises or project plans and strategies: See [Writing timeless documentation](https://developers.google.com/style/timeless-documentation) +- Using phrases like _simply_, _It's that simple_, _It's easy_, or _quickly_ in a procedure +- Over-politeness with the use of _please_: go straight to the point -#### ๐Ÿ’ก Shortcodes +#### ๐Ÿ’ก Shortcodes and callouts This doc uses Hugo with [Hextra theme](https://imfing.github.io/hextra/), which provides a variety of [shortcodes](https://imfing.github.io/hextra/docs/guide/shortcodes/) to enhance it and improve its readability. For example : -- [Steps](https://imfing.github.io/hextra/docs/guide/shortcodes/steps/) are well suited for the `/guides/` section, or for any tutorial. -- [Callouts](https://imfing.github.io/hextra/docs/guide/shortcodes/callout/) draw attention to an important information in the page. However, don't overuse them, as too many callouts can miss their point and make the page crowded. Limit callouts to one or two per page. +- [Steps](https://imfing.github.io/hextra/docs/guide/shortcodes/steps/) are well suited for the `/guides/` section, or for any tutorial + +Use GitHub-style callouts with a concise title on the marker line, as supported by the theme: + +```markdown +> [!NOTE] Current behaviour +> This information helps readers understand the current behaviour + +> [!WARNING] Back up your data +> Back up your application database before upgrading +``` + +Use the [Hextra callout shortcode](https://imfing.github.io/hextra/docs/guide/shortcodes/callout/) only when a GitHub-style callout can't provide the required rendering or behaviour. Don't overuse callouts: limit them to one or two per page. + +#### Front matter and examples + +- Give `title` a descriptive, SEO-oriented value without repeating "Clever Cloud", which the generated HTML title already includes. Keep `linkTitle` short, usually the product name, so it fits in the sidebar. +- Don't add `aliases` to a new page. Use them only to preserve URLs that existed previously. +- Remove `draft: true` when a page is ready to publish instead of keeping `draft: false` +- Keep commands literally copyable. Don't use shell-invalid placeholders or bracketed optional arguments in executable code blocks; show optional variants separately or explain where to add the flag. +- Add code comments only when they explain non-obvious behaviour +- Don't add a full stop to a short standalone line made of one simple sentence, especially a single-line code comment, label, or concise list item. Use normal terminal punctuation for developed or multi-sentence prose, including list items. +- Don't hard-wrap prose with formatting-only line breaks that don't affect rendering. Keep each paragraph on one logical line and rely on editor word wrap. +- Sort lists and tables alphabetically unless a functional or chronological order is more useful + +#### Dependencies and versions + +- All non-Docker runtimes provide a shared set of tools and version-management variables independently of the application's primary runtime. For example, `CC_NODE_VERSION` can select Node.js in a PHP application, while `CC_PHP_VERSION` can select PHP in a Node.js application. Other shared tools include Composer, Gradle, Hugo and Python. +- Prefer these dedicated environment variables and the package managers already provided by the runtime when they manage a dependency or its version. If a Mise task also needs the runtime-managed tool, derive its Mise version from the dedicated environment variable instead of hard-coding the version twice. +- For other deployment dependencies, prefer [Mise](https://mise.jdx.dev/) and a suitable backend such as [HTTP](https://mise.jdx.dev/dev-tools/backends/http.html) or [GitHub](https://mise.jdx.dev/dev-tools/backends/github.html) over custom download scripts, and pin versions when appropriate ### ๐Ÿ’… Style guide @@ -55,6 +83,10 @@ For example : - When importing from an external CSS tool, import the relevant classes only rather than the whole file - Opt for self hosting over CDN: When used in ``, it can impact site's performance. Using CDN for test purposes when submitting your PR and deploying a review app is totally fine, however. +### โœ… Validation + +Run `mise install` to install the development dependencies declared in `mise.toml`, then run `hugo` before submitting a change and fix any build error. Verify links, references, image paths, and shortcode syntax in the generated output. Inspect changed tabs, code blocks, cards, anchors, and copyable commands in the rendered HTML: a successful build alone doesn't prove that they render correctly. + ## ๐Ÿซถ Pull requests These are the guidelines when submitting or reviewing a PR in this repository. The better you follow them, the faster the is the review process. @@ -68,6 +100,40 @@ Priority goes to PRs that reference a problem addressed in an issue fitting the - **Keep it small:** The quality of the review is inversely proportional to the size of the PR. Smaller PRs simplify the reviewing process and increase the chances of getting constructive feedback. - **Accept the feedback:** If reviewers ask you to make changes, do it. If you disagree, explain why. If you aren't sure, ask for clarification. Don't nitpick on the feedback, and don't take it personally. +#### Commit messages + +For content updates, use `section(page): commit message`. The section and page identify the documentation area you changed: + +```text +addons(postgresql): document pg_partman support +applications(nodejs): clarify pnpm configuration +guides: add SvelteKit +``` + +Use `guides: add Product` when adding a deployment guide. Start the subject with a lowercase imperative verb. + +Changelog entries are the exception. Use `changelog: what you announce`, naming the product and its version or the change itself rather than starting with a verb: + +```text +changelog: Keycloak 26.7.3 +changelog: MySQL 8.0.46 and 8.4.10 +changelog: PostgreSQL 18 by default +changelog: images updates, 2026W34 +``` + +Commit a changelog entry together with the documentation pages and data files it relies on, so an announcement never lands before the pages it links to. + +For changes to the documentation structure, Hugo configuration or templates, deployment, CI, tooling, or dependencies, use the standard Conventional Commits format `type(scope): commit message`: + +```text +feat(hugo): add a shortcode for version tables +fix(ci): run Vale on shared content +refactor(layouts): simplify changelog rendering +chore(deps): update the Hextra theme +``` + +Keep content and structural changes in separate commits when possible so each commit can follow the appropriate convention. + ### ๐Ÿฅธ When reviewing a PR - **Latency:** Long PR review latency can be disappointing for the authors, and make merge conflicts arise in their branch. Long latency kills productivity and morale, so make sure to review PRs in a timely manner. diff --git a/README.md b/README.md index 2d3a7a6f9..39afbe9a4 100644 --- a/README.md +++ b/README.md @@ -1,205 +1,179 @@ -# Clever Cloud Documentation +# Clever Cloud documentation -This project is based on [Hugo](https://gohugo.io/) and uses [Hextra](https://imfing.github.io/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: +The Clever Cloud documentation site uses [Hugo](https://gohugo.io/) and the [Hextra](https://imfing.github.io/hextra/) theme. It provides responsive navigation, dark mode, full-text search and the following content features: -- [Complete Markdown support](https://imfing.github.io/hextra/docs/guide/markdown/) -- [Complete shortcodes set](https://imfing.github.io/hextra/docs/guide/shortcodes/) - [Diagrams](https://imfing.github.io/hextra/docs/guide/diagrams/) -- [LaTeX math formulae](https://imfing.github.io/hextra/docs/guide/latex/) +- [LaTeX mathematical notation](https://imfing.github.io/hextra/docs/guide/latex/) +- [Markdown](https://imfing.github.io/hextra/docs/guide/markdown/) +- [Shortcode support](https://imfing.github.io/hextra/docs/guide/shortcodes/) - [Syntax highlighting](https://imfing.github.io/hextra/docs/guide/syntax-highlighting/) -## See deployed Documentation +## Published documentation -- [Home page](https://www.clever.cloud/developers/) -- [Documentation](https://www.clever.cloud/developers/doc/) -- [API Documentation](https://www.clever.cloud/developers/api/) -- [Guides and Tutorials](https://www.clever.cloud/developers/guides/) -- [Reference Clever Tools CLI](https://www.clever.cloud/developers/doc/reference/cli/) -- [Reference Environment Variables](https://www.clever.cloud/developers/doc/reference/reference-environment-variables/) -- [Clever Cloud Platform Changelog](https://www.clever.cloud/developers/changelog/) +- [Clever Cloud documentation](https://www.clever.cloud/developers/) +- [API reference](https://www.clever.cloud/developers/api/) +- [Clever Tools CLI reference](https://www.clever.cloud/developers/doc/reference/cli/) +- [Environment variables reference](https://www.clever.cloud/developers/doc/reference/reference-environment-variables/) +- [Guides and tutorials](https://www.clever.cloud/developers/guides/) +- [Platform changelog](https://www.clever.cloud/developers/changelog/) +- [Technical documentation](https://www.clever.cloud/developers/doc/) -## Quickstart +## Local development -### Install Hugo +### Requirements -To begin your journey with the Clever Cloud Documentation, you need Hugo. You can: -- [Install it](https://gohugo.io/installation/) globally on your system -- Get its [binary](https://github.com/gohugoio/hugo/releases) and put it in the project's root +Install the following tools before building the site: -### Clone the project, preview locally +- [Git](https://git-scm.com/downloads) +- [Mise](https://mise.jdx.dev/getting-started.html) -Once your system is set up, clone this repository: +Mise installs the Go, Hugo Extended, markdownlint-cli2 and Vale versions declared in [`mise.toml`](./mise.toml). -```bash -git clone https://github.com/CleverCloud/documentation -``` +### Preview the site -Then: +Clone the repository and start Hugo's development server: -1. Go to the documentation folder: `cd documentation` -2. Run `hugo server` to build and start the local server +```bash +git clone https://github.com/CleverCloud/documentation.git +cd documentation +mise install +hugo server +``` -Local site is available on , 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](https://gohugo.io/commands/hugo_server/#options). +The site is available at and refreshes when you modify a file. See the [`hugo server` documentation](https://gohugo.io/commands/hugo_server/) for the available options. -## Deploying on Clever Cloud +## Deploy on Clever Cloud -The site is configured for Clever Cloud hosting with the `static` runtime and these required environment variables: +The site uses the Clever Cloud `static` runtime with the following environment variables: ```bash -# 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_DISABLE_MISE="true" CC_WEBROOT="public" CC_STATIC_AUTOBUILD_OUTDIR="public/developers" - -# Declare the location of the 404 custom page SERVER_ERROR_PAGE_404="developers/404.html" ``` +`CC_DISABLE_MISE` prevents Clever Cloud from installing the development dependencies because the static runtime provides and manages its deployment tools. Configure the route so its path ends in `/developers`, which matches the site's configured base URL and output directory. + > [!TIP] -> You can set the Hugo version with `CC_HUGO_VERSION` with a value like `0.152` +> Set `CC_HUGO_VERSION` to a supported version such as `0.164` to select the Hugo version used for deployment -## Contributing +## Contribute -You can contribute by [creating an issue](https://github.com/CleverCloud/documentation/issues) or [submitting a pull request](https://github.com/CleverCloud/documentation/pulls). If you use AI tools or LLMs, you'll find specific instructions for them: +You can contribute by [creating an issue](https://github.com/CleverCloud/documentation/issues) or [submitting a pull request](https://github.com/CleverCloud/documentation/pulls). Read the following project instructions before submitting a change: -- [AI tools and LLMs instructions](./.github/copilot-instructions.md) -- [Claude Code guidance](./CLAUDE.md) +- [Coding agent instructions](./AGENTS.md) - [Contributing guidelines](./CONTRIBUTING.md) -Clever Cloud documentation is also available following the [llms.txt specification](https://www.clever.cloud/developers/llms.txt). +The documentation is also available in the [llms.txt format](https://www.clever.cloud/developers/llms.txt). -## Adding a new page or guide +## Add a page or guide -To generates a file from a template (in `/archetypes`), run one of the following Hugo commands: +Use the archetypes in [`archetypes/`](./archetypes/) to create new content. These examples create a guide, a documentation page and an application runtime page: ```bash -hugo new content guides/.md -hugo new content/doc/administrate/.md -hugo new content --kind applications doc/applications/.md +hugo new content --kind guides guides/my-framework.md +hugo new content doc/administrate/my-feature.md +hugo new content --kind applications doc/applications/my-runtime.md ``` -In new page/guide front matter, `draft` is set to `true` to prevent it from being mistakenly published. - -> [!TIP] -> Use `hugo server --buildDrafts` command to preview drafts locally - -### Adding a changelog entry (internal only) +Archetypes set `draft: true` so regular builds exclude unfinished pages. Preview drafts locally with: -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 +```bash +hugo server --buildDrafts ``` -### Front matter configuration - -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`](https://gohugo.io/methods/page/type/) (optional) - - The type of content layout to apply. The value is a ``, set it to `docs` except in changelog. - -- [`weight`](https://gohugo.io/methods/page/weight/) (optional) - - The weight of the content, used to order the sidebar. The value is an ``, default is `0`. +Remove the `draft` field when the page is ready to publish. -- [`linkTitle`](https://gohugo.io/methods/page/linktitle/) (optional) - - The title of the content displayed in the sidebar. The value is a ``, default is the `title` value. +### Add a changelog entry -- [`title`](https://gohugo.io/methods/page/title/) (required) - - The title displayed in the main heading. The value is a ``. +Clever Cloud team members add an entry to `content/changelog/` for each significant platform update. Keep entries concise and focused on information users need to understand or act on. -- [`description`](https://gohugo.io/methods/page/description/) (recommended) - - The description displayed in meta-description for SEO purposes. The value is a ``. +Store each entry under its publication year and name it with the `MM-DD-title.md` format, for example `content/changelog/2026/08-26-product-update.md`. Multiple entries can share the same date. -- [`excludeSearch`](https://imfing.github.io/hextra/docs/guide/configuration/#search-index) (optional) - - Indicates whether the page should be indexed in search. Default is `false`, we recommend setting it to `true` for changelog entries. +### Configure front matter -- [`aliases`](https://gohugo.io/methods/page/aliases) (optional) - - Aliases redirects the user to the right page. The value is a list of ``, each string being a path to redirect from, relative to the base URL (without the `/developer`, for example: `/doc/docker`). +Hugo front matter stores page metadata. This project uses the following fields: -- [`comments`](https://gohugo.io/content-management/comments/) (optional) - - Whether to show the feedback block or not. The value is a ``, default is `true`. +| Field | Status | Purpose | +| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `aliases` | Optional | Redirects paths that existed previously. Omit the `/developers` base path, for example `/doc/docker`, and don't add an alias to a new page | +| `authors` | Changelog | Lists contributors with `name`, `link` and `image` fields | +| `date` | Changelog | Sets the publication date or date-time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format | +| `description` | Recommended | Provides the page's description for search results and search engines | +| `draft` | Optional | Excludes unfinished content from regular builds when set to `true`. Remove the field before publication | +| `excludeSearch` | Optional | Excludes the page from the search index when set to `true`. Set it for changelog entries | +| `keywords` | Optional | Lists search keywords | +| `linkTitle` | Optional | Sets a short sidebar label, usually the product name, and defaults to `title` | +| `tags` | Changelog | Lists lowercase product tags with consistent spelling | +| `title` | Required | Sets the page heading and search-oriented title. Avoid repeating the Clever Cloud name because the generated HTML title already includes it | +| `type` | Optional | Selects a content layout and uses `docs` outside the changelog | +| `weight` | Optional | Orders pages in the sidebar and defaults to `0` | -- [`draft`](https://gohugo.io/methods/page/draft/) (optional) - - Whether the page is a draft or not. The value is a ``, default is `false`. If set to `true`, the page is not built except if you use the `--buildDrafts` flag. - -- [`keywords`](https://gohugo.io/content-management/front-matter/#keywords) (optional) - - Keywords are used for SEO purposes. The value is a list of ``, each string being a keyword. - -- [`tags`](https://gohugo.io/content-management/front-matter/#taxonomies) (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 ``. - -- [`authors`](https://gohugo.io/content-management/front-matter/#taxonomies) (mostly used in changelog) - - Can be set to showcase the people behind the product. Authors are defined with a `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 `` type. - -- [`date`](https://gohugo.io/methods/page/date/) (mostly used in changelog) - - The date that will be displayed in the post. The value is a string in ISO 8601 like `yyyy-mm-dd`. - -For example, a changelog entry front matter could look like this: +A changelog entry can use the following front matter: ```yaml --- -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 +title: Product 1.2 is available +description: Product 1.2 adds a new feature and fixes an upgrade issue +date: 2026-08-26 tags: - - redis + - product authors: - - name: BlackYoup - link: https://github.com/BlackYoup - image: https://github.com/BlackYoup.png?size=40 + - name: Clever Cloud + link: https://github.com/CleverCloud + image: https://github.com/CleverCloud.png?size=40 excludeSearch: true --- ``` -### Adding an image +See the [Hugo front matter documentation](https://gohugo.io/content-management/front-matter/) for the supported formats and built-in fields. + +### Add an image -Adding an image can be useful to highlight an interface change, for example. Use such markdown syntax for that: +Store documentation images under `static/images/` and reference them with Markdown: ```markdown -![Alt text](/images/your-image.jpg "Title of the image") +![Alt text](/images/your-image.jpg "Image title") ``` -If needed, you can also use [the `figure` shortcode](https://gohugo.io/shortcodes/figure/) to add attributes such as a width limit: +Use Hugo's [`figure` shortcode](https://gohugo.io/shortcodes/figure/) when the image needs attributes such as a width limit: ```markdown -{{< figure src="/developers/images/your-image.jpg" alt="Alt text" title="Title of the image" width="800px">}} +{{< figure src="/developers/images/your-image.jpg" alt="Alt text" title="Image title" width="800px">}} ``` -- [Learn more about Hugo shortcodes](https://gohugo.io/shortcodes/) +### Add shared content -### Adding a new shared content +Create reusable Markdown in [`shared/`](./shared/) and include it in a page with: -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" %}}` +```markdown +{{% 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 +> Use `{{% content-raw "your-partial" %}}` when the shared file contains shortcode markup. Don't add headings to shared files because they don't appear in the page table of contents -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. +### Add a tooltip -To create a tooltip, add the term and its associated tooltip definition in the [`data/tooltips.toml`](./data/tooltips.toml) file. Once defined, tooltips automatically display when users hover over associated terms in the documentation. +Add a term and its definition to [`data/tooltips.toml`](./data/tooltips.toml). The site then displays the definition when readers hover over matching terms. -## Markdown Linting +## Validate changes -Hugo uses [Goldmark](https://github.com/yuin/goldmark), a Markdown parser written in Go, compliant with [CommonMark 0.30](https://spec.commonmark.org/). Therefore, for better readability and maintainability, all markdown files for this project are linted with [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2). We strongly recommend that you follow the validation rules described [here](https://github.com/DavidAnson/markdownlint#rules--aliases). +Run a production build before submitting a change: -This linter can be downloaded and run locally, or used via Visual Studio Code: +```bash +hugo +``` -- for Visual Studio Code -- as a `npm` package +The repository provides [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) rules in [`.markdownlint.jsonc`](./.markdownlint.jsonc) and CLI configuration in [`.markdownlint-cli2.jsonc`](./.markdownlint-cli2.jsonc), which excludes the paths listed in [`.gitignore`](./.gitignore). Run the version installed by Mise: -**Ignored markdown files** are listed in the `.markdownlintignore`. -**Ignored specifications**, such as some HTML tag of Web Components, are configured in the `.markdownlint.jsonc` +```bash +markdownlint-cli2 "**/*.md" +``` -## Editorial checks +Editorial checks use [Vale](https://vale.sh/). The pull request workflow checks changed lines, and Mise can run the same styles locally: -This project uses [Vale.sh](https://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. +```bash +vale README.md content shared +``` diff --git a/archetypes/applications.md b/archetypes/applications.md index edaf1e36e..75fc50b4e 100644 --- a/archetypes/applications.md +++ b/archetypes/applications.md @@ -16,8 +16,9 @@ To create a new XXX application, use the [Clever Cloud Console](https://console. ```bash clever create --type XXX ``` -* [Learn more about Clever Tools](/doc/cli/) -* [Learn more about Clever Cloud application deployment](/doc/quickstart/#create-an-application-step-by-step) + +- [Learn more about Clever Tools](/doc/cli/) +- [Learn more about Clever Cloud application deployment](/doc/quickstart/#create-an-application-step-by-step) ## Configure your XXX application @@ -25,7 +26,7 @@ clever create --type XXX XXX runtime only requires a working application listening on `0.0.0.0:8080`. -* [Learn more about environment variables on Clever Cloud](/doc/reference/reference-environment-variables/) +- [Learn more about environment variables on Clever Cloud](/doc/reference/reference-environment-variables/) ### Build phase @@ -35,11 +36,8 @@ During the build phase, ### XXX version - - ## Clever Tasks - ```bash clever create --type XXX --task "XXX" clever deploy # or clever restart if there is no code change diff --git a/archetypes/guides.md b/archetypes/guides.md index 9cc1ecef5..7012332b6 100644 --- a/archetypes/guides.md +++ b/archetypes/guides.md @@ -18,9 +18,9 @@ draft: true {{% steps %}} -### +### First step -### +### Second step {{% /steps %}} @@ -28,4 +28,4 @@ draft: true {{< cards >}} {{< card link="/developers/guides/" title="Card title" subtitle="Card subtiltle" icon="adjustments-horizontal" >}} -{{< /cards >}} \ No newline at end of file +{{< /cards >}} diff --git a/assets/css/custom.css b/assets/css/custom.css index f9a9d0ae0..19af3093f 100644 --- a/assets/css/custom.css +++ b/assets/css/custom.css @@ -52,6 +52,11 @@ html:not([class~="dark"]) .sidebar-active-item { Shortcodes ----------------------------- */ +/* Align card content to the top when cards have different heights */ +.hextra-card > .hx\:mt-auto { + margin-top: 0; +} + /* Hero buttons on home page */ .btn-primary { background-color: var(--purple-color); @@ -693,4 +698,31 @@ html[class~="dark"] .content table:not(.code-block table) tbody tr:nth-child(odd html[class~="dark"] .swagger-ui .responses-wrapper .response-header .response-toggle svg { fill: rgb(209 213 219); } - \ No newline at end of file + +/* "Edit this page" link: reuse the same arrow as external links. + The i18n string can only carry text, so the icon is appended here. + A mask keeps it on currentColor, so hover and dark mode follow the link. */ +.hextra-toc a[rel="noreferrer"]::after { + content: ""; + display: inline-block; + width: 1em; + height: 1em; + margin-left: 0.15em; + vertical-align: baseline; + background-color: currentColor; + -webkit-mask: url('data:image/svg+xml;utf8,') no-repeat center / contain; + mask: url('data:image/svg+xml;utf8,') no-repeat center / contain; +} + +/* Show the Deploy group expanded on the documentation home page. + That page is the only one where no sidebar entry is active, which is what + `:not(:has(...))` keys on: as soon as a page is selected, the theme takes + over and only its own group stays open. Height and chevron rotation mirror + what the theme applies to `li.open`. */ +.hextra-sidebar-container ul:not(:has(.hextra-sidebar-active-item)) li:has(> .hextra-sidebar-item > a[href$="/doc/deploy/"]) > .hextra-sidebar-children { + height: auto; + padding-top: 0.25rem; +} +.hextra-sidebar-container ul:not(:has(.hextra-sidebar-active-item)) li:has(> .hextra-sidebar-item > a[href$="/doc/deploy/"]) > .hextra-sidebar-item > .hextra-sidebar-collapsible-button > svg > path { + rotate: 90deg; +} diff --git a/check-internal-links.py b/check-internal-links.py new file mode 100755 index 000000000..ce1751b63 --- /dev/null +++ b/check-internal-links.py @@ -0,0 +1,1118 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.9" +# dependencies = [] +# /// +"""Check internal hyperlinks in a built Hugo site. + +Scope: only. Assets (img/src, srcset, link, script) have different +semantics and exemptions and are deliberately left to the deployed +`linkchecker` job. + +Complements that job, which follows redirects and checks external URLs but +never validates URL fragments. This one runs offline on the build output +and reports what it cannot see: + + broken the target page does not exist + dead-alias the link lands on an alias whose chain ends nowhere + alias-loop the redirect chain loops back on itself + lost-anchor the link lands on an alias AND carries a fragment; a Hugo + alias is a with no JavaScript, + which drops the fragment, so the reader lands at the top + anchor the target exists but has no matching id + redirect the link lands on an alias, so it costs an extra hop (note) + +Same-origin links outside this build are served by another application and +are simply set aside: `linkchecker` already covers them in CI. + +`source_locations` are heuristic candidates: the Markdown lines whose text +contains the offending URL. They can miss a link produced by a template or +by hugo.yaml, so `rendered_pages` is always reported as well. + +Notes are summarised as counts by default and only listed with -d: they +need no action here. `--format json` emits a stable machine-readable report +on stdout for tooling and agents; diagnostics go to stderr. + +Resolution runs against an exact, case-sensitive index of the files in the +build. macOS is case-insensitive and Linux is not, so an `is_file()` probe +would accept /doc/Foo locally and 404 in CI; the index makes both agree. +URL paths are percent-decoded and normalised before the prefix boundary is +tested, so a link climbing out of the prefix with `..` cannot be validated +against the wrong file. + +Ownership: a path under the baseURL prefix belongs to this build and must +resolve, unless it is declared with --external-prefix (other applications +are deployed under the same prefix). + +The HTML element is not honoured; the build contains none, and +supporting it would need its own same-origin and ownership checks. + +Usage: + hugo # writes to publishDir + ./check-internal-links.py # defaults to public/developers + uv run check-internal-links.py -d # also list the non-blocking notes + uv run check-internal-links.py --format json # machine-readable, stdout only + uv run check-internal-links.py --root some/dir --prefix /developers + +Exit codes: 0 clean, 1 problems found, 2 bad invocation or missing build. +""" + +from __future__ import annotations + +import argparse +import difflib +import json +import os +import posixpath +import re +import shutil +import sys +from collections import Counter, defaultdict +from concurrent.futures import ProcessPoolExecutor +from concurrent.futures.process import BrokenProcessPool +from html.parser import HTMLParser +from pathlib import Path +from time import perf_counter +from typing import TYPE_CHECKING, NamedTuple, NoReturn + +if TYPE_CHECKING: + from collections.abc import Iterable, Sequence + + Attrs = Sequence[tuple[str, str | None]] +from urllib.parse import unquote, urljoin, urlsplit, urlunsplit + +# Paths served under the baseURL prefix by something other than this build. +DEFAULT_EXTERNAL = ("/developers/clever-components",) +# Pages whose anchors are generated client-side, absent from static HTML. +DEFAULT_SKIP_ANCHORS = ("api/v2",) +DEFAULT_SOURCES = ("content", "shared") +DEFAULT_CONFIGS = ("hugo.yaml",) + +SKIPPED_SCHEMES = ("mailto:", "tel:", "javascript:", "data:") +DEFAULT_PORTS = {"http": "80", "https": "443"} +ALIAS_HOP_LIMIT = 10 # a Hugo alias chain is normally one hop +MAX_SUGGESTIONS = 5 # near-miss anchors offered as a fix +SUGGESTION_CUTOFF = 0.4 # loose enough to catch prefix- -> path-routing +MAX_SOURCE_LINES = 4 # source lines printed per finding +MAX_PAGES_LISTED = 2 # rendered pages printed before "+N more" +CHUNKS_PER_WORKER = 4 # how finely the page list is split across workers +CHUNK_CEILING = 64 # never hand a worker more than this in one go +HELP_WIDTH = 96 # usage and help never wrap wider than this + +EXIT_OK, EXIT_FINDINGS, EXIT_MISUSE = 0, 1, 2 +GLYPHS = "โœ“โœ—ยทโ†’" # dropped together when the stream cannot encode them + + +class Kind(NamedTuple): + """A category of finding: how to name it, explain it, and how bad it is.""" + + name: str + title: str + explanation: str + blocking: bool + + +KINDS: tuple[Kind, ...] = ( + Kind( + "broken", + "Broken targets", + "The target does not exist in the build.", + blocking=True, + ), + Kind( + "dead-alias", + "Redirects to missing pages", + "The link lands on a redirect whose own destination is missing.", + blocking=True, + ), + Kind( + "alias-loop", + "Redirect loops", + "The chain of redirects comes back on itself and never lands.", + blocking=True, + ), + Kind( + "lost-anchor", + "Fragments lost in redirects", + "A redirect cannot carry a #fragment: the reader lands at the top.", + blocking=True, + ), + Kind( + "anchor", + "Missing anchors", + "The page exists but has no element with that id, usually a renamed heading.", + blocking=True, + ), + Kind( + "redirect", + "Redirects", + "These resolve through an alias. Point them at the destination to save a hop.", + blocking=False, + ), +) +KIND_ORDER = [kind.name for kind in KINDS] +BLOCKING = frozenset(kind.name for kind in KINDS if kind.blocking) +NOTE_LABEL = {"redirect": "redirecting"} + + +# -------------------------------------------------------------------------- +# Small pure helpers +# -------------------------------------------------------------------------- + + +def canon_origin(scheme: str, netloc: str) -> str: + """Canonical scheme://host, lowercased and without a default port.""" + scheme = (scheme or "").lower() + host = (netloc or "").lower() + port = DEFAULT_PORTS.get(scheme) + if port and host.endswith(f":{port}"): + host = host[: -len(port) - 1] + return f"{scheme}://{host}" if host else "" + + +def parse_refresh(content: str) -> str | None: + """Target of a zero-delay meta refresh, else None. + + Only a zero delay is a Hugo alias. A page with a real timed refresh is + a normal page and must still be crawled. + """ + delay, separator, rest = content.partition(";") + if not separator: + return None + try: + if float(delay.strip()) != 0: + return None + except ValueError: + return None + rest = re.sub(r"^url\s*=\s*", "", rest.strip(), count=1, flags=re.IGNORECASE) + if rest[:1] == rest[-1:] and rest[:1] in ("'", '"'): + rest = rest[1:-1] + return rest.strip() or None + + +def wanted_anchor(fragment: str) -> str | None: + """The id a fragment targets, or None when it targets no id. + + `#top` scrolls to the top of the document with no element of that name, + and a `:~:` text directive is not an id at all. + """ + frag = unquote(fragment) + if ":~:" in frag: + frag = frag.split(":~:", 1)[0] + if not frag or frag.lower() == "top": + return None + return frag + + +def under(path: str, prefix: str) -> bool: + """True if `path` equals `prefix` or lives under it. Never a raw startswith.""" + return path == prefix or path.startswith(prefix.rstrip("/") + "/") + + +def display_path(path: str) -> str: + """Path relative to the invocation directory, in POSIX form. + + Always relative when it can be computed: an absolute path would leak + the local layout into a published JSON artifact and make the report + differ between runners. + """ + try: + return os.path.relpath(path, Path.cwd()).replace(os.sep, "/") + except ValueError: # different volume on Windows + return path.replace(os.sep, "/") + + +def plural(count: int, singular: str, many: str | None = None) -> str: + return f"{count:,} {singular if count == 1 else (many or singular + 's')}" + + +def cpu_limit() -> int: + return os.cpu_count() or 1 + + +# -------------------------------------------------------------------------- +# Parsing +# -------------------------------------------------------------------------- + + +class Page(HTMLParser): + """Collect hyperlinks, anchor ids and any meta refresh from one page. + + A real parser rather than a regex: it handles uppercase attributes, + single or unquoted values and character references. It also puts + - - - \ No newline at end of file diff --git a/layouts/section.markdown.md b/layouts/section.markdown.md new file mode 100644 index 000000000..bff59535f --- /dev/null +++ b/layouts/section.markdown.md @@ -0,0 +1 @@ +{{ partial "markdown-output.md" . }} diff --git a/layouts/shortcodes/callout.markdown.md b/layouts/shortcodes/callout.markdown.md new file mode 100644 index 000000000..b839a672e --- /dev/null +++ b/layouts/shortcodes/callout.markdown.md @@ -0,0 +1,16 @@ +{{- /* Markdown output: a callout becomes a GitHub alert, so callouts and +alert-style blockquotes read the same way. See render-blockquote-alert.markdown.md +for the sentinels and for why a callout carrying a code block is not quoted. */ -}} +{{- $types := dict "info" "NOTE" "warning" "WARNING" "error" "CAUTION" -}} +{{- $marker := printf "\ue000%s\ue001" (index $types (.Get "type" | default "default") | default "NOTE") -}} +{{- with .Get "emoji" }}{{ $marker = printf "%s %s" $marker . }}{{ end -}} +{{- $body := .InnerDeindent | markdownify -}} +{{- if strings.Contains $body "{{ $marker }}

+{{ $body }} +{{- else -}} +
+

{{ $marker }}

+{{ $body }} +
+{{- end -}} diff --git a/layouts/shortcodes/card.markdown.md b/layouts/shortcodes/card.markdown.md new file mode 100644 index 000000000..e4c9177d9 --- /dev/null +++ b/layouts/shortcodes/card.markdown.md @@ -0,0 +1,5 @@ +{{- /* Markdown output: a card becomes a list item with its link and subtitle. */ -}} +{{- $link := .Get "link" -}} +{{- $title := .Get "title" | default $link -}} +{{- $subtitle := .Get "subtitle" -}} +
  • {{ with $link }}{{ partial "md-escape.md" $title }}{{ else }}{{ partial "md-escape.md" $title }}{{ end }}{{ with $subtitle }}: {{ . | markdownify }}{{ end }}
    • diff --git a/layouts/shortcodes/cards.markdown.md b/layouts/shortcodes/cards.markdown.md new file mode 100644 index 000000000..97613b11d --- /dev/null +++ b/layouts/shortcodes/cards.markdown.md @@ -0,0 +1,2 @@ +{{- /* Markdown output: cards become a plain list of links. */ -}} +
      {{ .Inner }}
    diff --git a/layouts/shortcodes/imgproc.html b/layouts/shortcodes/imgproc.html deleted file mode 100644 index 37e0e181b..000000000 --- a/layouts/shortcodes/imgproc.html +++ /dev/null @@ -1,60 +0,0 @@ -{{- $context := . -}} -{{- $caption := .Get "caption" -}} -{{- $image := .Get "image" -}} -{{- $width := 0 -}} -{{- $height := 0 -}} -{{- $imageStyle := .Get "imageStyle" -}} - -{{/* Image processing options */}} -{{- $method := .Get "method" | default "Resize" | humanize -}} -{{- $options := .Get "options" | default "900x webp q95" -}} - -{{- if and $image (not (urls.Parse $image).Scheme) -}} - {{/* Process images in assets */}} - {{- with resources.Get $image -}} - {{- $processed := "" -}} - {{- if eq $method "Resize" -}} - {{- $processed = (.Resize $options) -}} - {{- else if eq $method "Fit" -}} - {{- $processed = (.Fit $options) -}} - {{- else if eq $method "Fill" -}} - {{- $processed = (.Fill $options) -}} - {{- else if eq $method "Crop" -}} - {{- $processed = (.Crop $options) -}} - {{- else -}} - {{- errorf "Invalid image processing command: Must be one of Crop, Fit, Fill or Resize." -}} - {{- end -}} - {{- $width = $processed.Width -}} - {{- $height = $processed.Height -}} - {{- $image = $processed.RelPermalink -}} - {{- else -}} - {{/* Otherwise, use relative link of the image */}} - {{- if hasPrefix $image "/" -}} - {{- $image = relURL (strings.TrimPrefix "/" $image) -}} - {{- end -}} - {{- end -}} -{{- end -}} - - - - -{{- $padding := "p-4" -}} -{{- with $caption -}} - {{- $padding = "pt-4 px-4" -}} -{{- end -}} - -{{- with $caption -}} -
    {{- $caption | markdownify -}}
    -{{- end -}} - -     \ No newline at end of file diff --git a/layouts/shortcodes/kubernetes_version.html b/layouts/shortcodes/kubernetes_version.html new file mode 100644 index 000000000..a564e2a68 --- /dev/null +++ b/layouts/shortcodes/kubernetes_version.html @@ -0,0 +1,3 @@ +{{- $key := .Get 0 -}} +{{- $value := index hugo.Data.kubernetes_versions $key -}} +{{- if reflect.IsSlice $value -}}{{ delimit $value ", " }}{{- else -}}{{ $value }}{{- end -}} diff --git a/layouts/shortcodes/runtime_version.html b/layouts/shortcodes/runtime_version.html index 084945473..8ca5e4880 100644 --- a/layouts/shortcodes/runtime_version.html +++ b/layouts/shortcodes/runtime_version.html @@ -1 +1 @@ -{{ $software := .Get 0 }}{{ $key := or (.Get 1) "default" }}{{ with index .Site.Data.runtime_versions $software }}{{ with index . $key }}{{ index . 0 }}{{ end }}{{ end }} \ No newline at end of file +{{ $software := .Get 0 }}{{ $key := or (.Get 1) "default" }}{{ with index hugo.Data.runtime_versions $software }}{{ with index . $key }}{{ index . 0 }}{{ end }}{{ end }} \ No newline at end of file diff --git a/layouts/shortcodes/runtimes_versions.html b/layouts/shortcodes/runtimes_versions.html index beea16c45..5d5b163b7 100644 --- a/layouts/shortcodes/runtimes_versions.html +++ b/layouts/shortcodes/runtimes_versions.html @@ -1,5 +1,5 @@ {{ $software := or (.Get 0) }} -{{ $version_list := .Site.Data.runtime_versions }} +{{ $version_list := hugo.Data.runtime_versions }} {{ with index $version_list $software }} {{ $default := .default | default (slice) }} diff --git a/layouts/shortcodes/software_versions_shared_dedicated.html b/layouts/shortcodes/software_versions_shared_dedicated.html index 448e93013..cb2876c9b 100644 --- a/layouts/shortcodes/software_versions_shared_dedicated.html +++ b/layouts/shortcodes/software_versions_shared_dedicated.html @@ -1,5 +1,5 @@ {{ $software := or (.Get 0) }} -{{ $version_list := .Site.Data.software_versions_shared_dedicated }} +{{ $version_list := hugo.Data.software_versions_shared_dedicated }} {{ $software_versions := index $version_list $software }} {{ $has_dev := false }} diff --git a/layouts/shortcodes/tabs.markdown.md b/layouts/shortcodes/tabs.markdown.md new file mode 100644 index 000000000..bf39a9f7b --- /dev/null +++ b/layouts/shortcodes/tabs.markdown.md @@ -0,0 +1,6 @@ +{{- /* Markdown output: every tab is emitted in order, each under its own label. */ -}} +{{- .Inner -}} +{{- range ($.Store.Get "tabs" | default slice) -}} +

    {{ partial "md-escape.md" .name }}

    +{{ .content | markdownify }} +{{- end -}} diff --git a/layouts/shortcodes/tooltip.html b/layouts/shortcodes/tooltip.html index 807e5e763..b1e112d88 100644 --- a/layouts/shortcodes/tooltip.html +++ b/layouts/shortcodes/tooltip.html @@ -3,7 +3,7 @@ {{- errorf "missing tooltip title" -}} {{- end -}} {{ .Scratch.Set "title" $title }} -{{ $def := index .Site.Data.tooltips (.Scratch.Get "title") }} +{{ $def := index hugo.Data.tooltips (.Scratch.Get "title") }} {{- if not $def -}} {{- errorf "%s not in tooltips" $title -}} diff --git a/layouts/shortcodes/tooltip.markdown.md b/layouts/shortcodes/tooltip.markdown.md new file mode 100644 index 000000000..2643987a3 --- /dev/null +++ b/layouts/shortcodes/tooltip.markdown.md @@ -0,0 +1,4 @@ +{{- /* Markdown output: the tooltip becomes its definition in parentheses. */ -}} +{{- $title := .Get "title" -}} +{{- $def := index hugo.Data.tooltips $title -}} +{{- .Inner }}{{ with $def }} ({{ partial "md-escape.md" . }}){{ end -}} diff --git a/layouts/shortcodes/youtube.markdown.md b/layouts/shortcodes/youtube.markdown.md new file mode 100644 index 000000000..a9939b717 --- /dev/null +++ b/layouts/shortcodes/youtube.markdown.md @@ -0,0 +1,5 @@ +{{- /* Markdown output: the embedded player becomes a plain link to the video. */ -}} +{{- $id := or (.Get "id") (.Get 0) -}} +{{- with $id -}} +

    Watch the video on YouTube

    +{{- end -}} diff --git a/mise.toml b/mise.toml new file mode 100644 index 000000000..2f2a3584e --- /dev/null +++ b/mise.toml @@ -0,0 +1,5 @@ +[tools] +go = "1.26" +hugo-extended = "0.164" +markdownlint-cli2 = "latest" +vale = "latest" diff --git a/shared/ask-for-help.md b/shared/ask-for-help.md new file mode 100644 index 000000000..50224262d --- /dev/null +++ b/shared/ask-for-help.md @@ -0,0 +1 @@ +Can't find what you're looking for? Contact the [support team](/doc/find-help/), or [open an issue](https://github.com/CleverCloud/documentation/issues) to suggest an addition to this page. diff --git a/shared/blackfire.md b/shared/blackfire.md index 786649e4d..49e1cfb10 100644 --- a/shared/blackfire.md +++ b/shared/blackfire.md @@ -2,4 +2,4 @@ You can use [Blackfire](https://www.blackfire.io/) to monitor your application on Clever Cloud. -Please refer to our [Blackfire documentation](/doc/metrics/blackfire) to configure it for your application. +Please refer to our [Blackfire documentation](/doc/develop/observability/blackfire) to configure it for your application. diff --git a/shared/cached-dependencies.md b/shared/cached-dependencies.md index 4477905f9..9ef8f632d 100644 --- a/shared/cached-dependencies.md +++ b/shared/cached-dependencies.md @@ -2,7 +2,7 @@ #### Enabling dependencies caching -You can enable dependencies caching by adding the `CC_CACHE_DEPENDENCIES=true` [environment variable](#setting-up-environment-variables-on-clever-cloud) in your application. It is enabled by default only for rust and haskell applications. +You can enable dependencies caching by adding the `CC_CACHE_DEPENDENCIES=true` [environment variable](/doc/develop/common-configuration/environment-variables/) in your application. It is enabled by default only for rust and haskell applications. #### Disabling dependencies caching diff --git a/shared/create-application.md b/shared/create-application.md index f64071aaf..15336b2c9 100644 --- a/shared/create-application.md +++ b/shared/create-application.md @@ -3,15 +3,15 @@ ### With the web console -Refer to [Quickstart](/doc/quickstart) for more details on application creation via the console. +Refer to [Quickstart](/doc/getting-started) for more details on application creation via the console. ### With the Clever Tools CLI -1. Make sure you have clever-tools installed locally or follow our [CLI getting started](/doc/cli/) guide. +1. Make sure you have clever-tools installed locally or follow our [CLI getting started](/doc/manage/cli/) guide. 2. In your code folder, do `clever create --type --region --org ` where : 1. `type` is the type of technology you rely on 2. `app-name` the name you want for your application, 3. `zone` deployment zone (`par` for Paris and `mtl` for Montreal) 4. `org` the organisation ID the application will be created under. -Refer to [clever create](/doc/cli/applications/) for more details on application creation with Clever Tools. +Refer to [clever create](/doc/manage/cli/applications/) for more details on application creation with Clever Tools. diff --git a/shared/db-backup.md b/shared/db-backup.md index 367e169de..fd10fc0d4 100644 --- a/shared/db-backup.md +++ b/shared/db-backup.md @@ -1,5 +1,5 @@ ## Database Daily Backup and Retention -By default, Clever Cloud performs a free backup every day, with a retention of seven days. Retention and frequency can be customized for Premium customers. +By default, Clever Cloud performs a free backup every day, with a retention of seven days. Retention and frequency can be customized by contacting [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). Each backup can be found in the add-on dashboard in the web console, along with the credentials. diff --git a/shared/db-migration.md b/shared/db-migration.md index 3d384af32..45e48bf7d 100644 --- a/shared/db-migration.md +++ b/shared/db-migration.md @@ -7,4 +7,4 @@ The duration may vary depending on how much data your add-on has. Your database If you want to restart your add-on or update to the last supported version of the current branch, migrate it to the same plan, version, zone. -- [More Clever Cloud Tips and Tricks](/doc/best-practices/tips_and_tricks/) +- [More Clever Cloud Tips and Tricks](/doc/tips-and-tricks/) diff --git a/shared/deploy-ftp.md b/shared/deploy-ftp.md index 18b019489..a604570b5 100644 --- a/shared/deploy-ftp.md +++ b/shared/deploy-ftp.md @@ -2,7 +2,7 @@ Make sure you have [Filezilla](https://filezilla-project.org/) or an other FTP software installed in your machine. -When you chose to deploy your application via FTP at the application creation, the system creates a free [FS Bucket](/doc/addons/fs-bucket) with an ID matching your application's ID. +When you chose to deploy your application via FTP at the application creation, the system creates a free [FS Bucket](/doc/deploy/storage/fs-bucket) with an ID matching your application's ID. Find the FTP credentials in the configuration tab of this particular FS Bucket. @@ -10,4 +10,4 @@ Just follow the instructions of your FTP Software to send code to Clever Cloud. โš ๏ธ **An FTP application automatically starts once you create the application, even if you don't send any code yet.** -Refer to [Quick Start - FTP deployment](/doc/quickstart#ftp-deployment) for more details. +Refer to [Quick Start - FTP deployment](/doc/getting-started#choose-how-to-deploy) for more details. diff --git a/shared/deploy-git.md b/shared/deploy-git.md index bed2a8ef4..dc5fcda27 100644 --- a/shared/deploy-git.md +++ b/shared/deploy-git.md @@ -16,4 +16,4 @@ 5. Now push your application on Clever Cloud with `git push master` -Refer to [git deployments](/doc/quickstart) for more details. +Refer to [git deployments](/doc/getting-started) for more details. diff --git a/shared/env-injection.md b/shared/env-injection.md index aa02a543d..2ae06e989 100644 --- a/shared/env-injection.md +++ b/shared/env-injection.md @@ -1,8 +1,8 @@ ## Environment injection -Clever Cloud injects environment variables from your application settings as mentioned in [setting up environment variables](#setting-up-environment-variables-on-clever-cloud) and is also injecting in your application production environment, those from your [linked add-ons](#linking-a-database-or-any-other-add-on-to-your-application). +Clever Cloud injects environment variables from your application settings as mentioned in [setting up environment variables](/doc/develop/common-configuration/environment-variables/) and is also injecting in your application production environment, those from your [linked add-ons](#linking-a-database-or-any-other-add-on-to-your-application). ### Custom build configurations On Clever Cloud you can define some build configuration: like the app folder to deploy or the path to validate your application deployment is ready -To do that follow the [documentation here](/doc/reference/reference-environment-variables/#variables-you-can-define) and add the environment variable you need. +To do that follow the [documentation here](/doc/develop/common-configuration/environment-variables/reference/#variables-you-can-define) and add the environment variable you need. diff --git a/shared/git-push.md b/shared/git-push.md deleted file mode 100644 index bba67c947..000000000 --- a/shared/git-push.md +++ /dev/null @@ -1,21 +0,0 @@ -## Push your code - -Once you complete these steps, commit your content to the local repository and deploy it: - -```bash -git add . -git commit -m "First deploy" -clever deploy -clever open -``` - -You can display your website's URL or add a custom domain to it (you'll need to configure DNS): - -```bash -clever domain -clever domain add your.website.tld -``` - -## 404 page location - -If you need to use a specific page for 404 errors, define its location with `SERVER_ERROR_PAGE_404` environment variable from Static Web Server, used as default in `static` runtime. For example : `SERVER_ERROR_PAGE_404=404.html`. diff --git a/shared/java-env-injection.md b/shared/java-env-injection.md new file mode 100644 index 000000000..eee454112 --- /dev/null +++ b/shared/java-env-injection.md @@ -0,0 +1,23 @@ +## Environment injection + +Clever Cloud exposes [environment variables defined for your application](#setting-up-environment-variables-on-clever-cloud) alongside those provided by linked add-ons. Read a standard variable such as `MY_VARIABLE` from the process environment with: + +```java +String value = System.getenv("MY_VARIABLE"); +``` + +### Java system properties + +By default, Clever Cloud also passes variables to the generated launch command as Java system properties using `-D` options. When this command runs your application in the same JVM, retrieve a property with `System.getProperty("MY_VARIABLE")`. + +Variable names containing a dot (`.`) are not exported to the process environment. The generated launch command only receives them as Java system properties. For example, if you define `my.app.config=production` for your application, Clever Cloud adds `-Dmy.app.config=production` to the generated launch command. + +A Maven or Gradle deployment goal can start the application in another JVM. In this case, forwarding system properties depends on the plugin or task configuration. When the property reaches the application JVM, retrieve its value with: + +```java +String value = System.getProperty("my.app.config"); // returns "production" +``` + +This mechanism can configure frameworks such as Spring Boot or Quarkus without modifying configuration files. Prefer standard environment variable names for portable application configuration. + +Setting [`CC_RUN_COMMAND`](#custom-run-command) replaces the generated launch command, so Clever Cloud no longer adds these `-D` options automatically. With a custom run command, use standard environment variable names and map them in your application configuration. diff --git a/shared/kv-explorer.md b/shared/kv-explorer.md index 29ce77bec..730ab3fc4 100644 --- a/shared/kv-explorer.md +++ b/shared/kv-explorer.md @@ -16,6 +16,6 @@ At the bottom of the page, you'll find an integrated terminal that works like a KV Explorer is in Beta testing phase and we'll improve it over the coming months, thanks to your feedback and suggestions. -- [ Share your feedback on KV Explorer](https://github.com/CleverCloud/Community/discussions/categories/kv-explorer) +- [Share your feedback on KV Explorer](https://github.com/CleverCloud/Community/discussions/categories/kv-explorer) ![KV Explorer](/images/kv-explorer.webp "The KV Explorer tool in the Console") diff --git a/shared/link-addon.md b/shared/link-addon.md index 8e8acfafb..246b32478 100644 --- a/shared/link-addon.md +++ b/shared/link-addon.md @@ -4,7 +4,7 @@ By linking an application to an add-on, the application has the add-on environme ### On add-on creation -Many add-ons do exist on Clever Cloud: refer to [the full list](/doc/addons) and check add-ons dedicated pages for full instructions. +Many add-ons do exist on Clever Cloud: refer to [the full list](/doc/deploy/addons) and check add-ons dedicated pages for full instructions. During add-on creation, an **Applications** screen appears, with a list of your applications. You can toggle the button to *Link* and click *next*. If you finish the process of add-on creation, the application is automatically linked to it. diff --git a/shared/more-config.md b/shared/more-config.md index e1fa63df6..7d6254b06 100644 --- a/shared/more-config.md +++ b/shared/more-config.md @@ -2,8 +2,8 @@ Need more configuration? To run a script at the end of your deployment? To add your private SSH key to access private dependencies? -Go check the [Common configuration page](/doc/reference/common-configuration). +Go check the [Configure applications page](/doc/develop/common-configuration). -You may want to have an advanced usage of your application, in which case we recommend you to read the **Administrate** documentation section. +For advanced usage of your application, read the [Develop](/doc/develop/) section. -If you can't find something or have a specific need like using a non supported version of a particular software, please reach out to the [support](/doc/find-help/support). +If you can't find something or have a specific need like using a non supported version of a particular software, please reach out to the [support](/doc/find-help/). diff --git a/shared/new-relic.md b/shared/new-relic.md index 205446214..49ad08a58 100644 --- a/shared/new-relic.md +++ b/shared/new-relic.md @@ -2,4 +2,4 @@ You can use [New Relic](https://www.newrelic.com/) to monitor your application on Clever Cloud. -Please refer to our [New Relic documentation](/doc/metrics/new-relic) to configure it for your application. +Please refer to our [New Relic documentation](/doc/develop/observability/new-relic) to configure it for your application. diff --git a/shared/private-composer-repositories.md b/shared/private-composer-repositories.md new file mode 100644 index 000000000..9370d9f5b --- /dev/null +++ b/shared/private-composer-repositories.md @@ -0,0 +1,34 @@ +## Private Composer repositories + +Composer can authenticate with private package repositories through the `COMPOSER_AUTH` [environment variable](/doc/develop/common-configuration/environment-variables/). Its value is a JSON object containing Composer authentication settings, such as HTTP Basic, OAuth or an access token. + +For example, to use [Private Packagist](https://packagist.com/), add its repository to your `composer.json`, replacing `ORGANISATION` with its short name: + +```json +{ + "repositories": [ + { + "type": "composer", + "url": "https://repo.packagist.com/ORGANISATION" + }, + { + "packagist.org": false + } + ] +} +``` + +Then define `COMPOSER_AUTH` for your application with the username and token provided by Private Packagist: + +```json +{ + "http-basic": { + "repo.packagist.com": { + "username": "PACKAGIST_USERNAME", + "password": "PACKAGIST_TOKEN" + } + } +} +``` + +Composer reads this variable automatically during `composer install`. Never commit credentials to your repository. If you use a local `auth.json` file, add it to `.gitignore`. See the [Composer authentication documentation](https://getcomposer.org/doc/articles/authentication-for-private-packages.md) for other providers and authentication methods. For a private Git repository accessed over SSH, configure a [private SSH key](/doc/develop/common-configuration/#private-ssh-key) instead. diff --git a/shared/redirectionio.md b/shared/redirectionio.md index 04dbcaa2d..59bb5b136 100644 --- a/shared/redirectionio.md +++ b/shared/redirectionio.md @@ -2,10 +2,9 @@ [Redirection.io](https://redirection.io) can help reduce HTTP traffic issues on your website. It gives complete control over how HTTP requests are handled, which helps make it SEO-friendly. You can link any application to a Redirection.io project by setting the following environment variables. Port allocation is managed automatically by [Request Flow](/doc/develop/request-flow/). -| Name | Description | Default value | -|-----------------------|------------------------------|--------------------------------| -| `CC_REDIRECTIONIO_PROJECT_KEY` | The Redirection.io project key | | -| `CC_REDIRECTIONIO_FORWARD_PORT` | Override the port Redirection.io forwards traffic to (optional) | | -| `CC_REDIRECTIONIO_INSTANCE_NAME` | The name of your application (optional) | | +| Name | Description | Default value | +| -------------------------------- | --------------------------------------------------------------- | ------------- | +| `CC_REDIRECTIONIO_PROJECT_KEY` | The Redirection.io project key | | +| `CC_REDIRECTIONIO_INSTANCE_NAME` | The name of your application (optional) | | - [Learn more about Redirection.io](https://redirection.io/) diff --git a/shared/request-flow.md b/shared/request-flow.md index 1fe40c7f3..60dcd750e 100644 --- a/shared/request-flow.md +++ b/shared/request-flow.md @@ -1,15 +1,17 @@ -## Request Flow: Varnish, Redirection.io, custom proxy +## Request Flow: Varnish, Redirection.io, OAuth2 Proxy, custom proxy -Request Flow automatically chains reverse proxies between port `8080` (public) and your application, managing port allocation with no manual configuration. Supported services are activated by their presence in your project: +Request Flow automatically chains reverse proxies between port `8080` (public) and your application, allocating middleware ports automatically. Some services are detected from your configuration, while others must be listed explicitly in `CC_REQUEST_FLOW`: - **Otoroshi Challenge**: set `OTOROSHI_CHALLENGE_SECRET` - **Varnish**: add a `clevercloud/varnish.vcl` file or set `CC_VARNISH_FILE` - **Redirection.io**: set `CC_REDIRECTIONIO_PROJECT_KEY` +- **OAuth2 Proxy**: set `CC_REQUEST_FLOW=oauth2-proxy` and its `OAUTH2_PROXY_*` settings -All three can be active simultaneously. To control the order, set `CC_REQUEST_FLOW` (e.g. `redirectionio,varnish`). To add a custom middleware, include `custom` in the chain and define `CC_REQUEST_FLOW_CUSTOM` with `@@LISTEN_PORT@@` and `@@FORWARD_PORT@@` placeholders. To block public access, set `CC_REQUEST_FLOW=block`. +Multiple services can run simultaneously. Setting `CC_REQUEST_FLOW` replaces automatic detection, so list every service you need in order (e.g. `oauth2-proxy,varnish`). To add a custom middleware, include `custom` in the chain and define `CC_REQUEST_FLOW_CUSTOM` with `@@LISTEN_PORT@@` and `@@FORWARD_PORT@@` placeholders. To block public access, set `CC_REQUEST_FLOW=block`. -When at least one middleware is active, your application must listen on port `9000` instead of `8080`. +If your application manages its own HTTP server, configure it to listen on port `9000` instead of `8080` when at least one middleware is active. Clever Cloud handles this automatically for runtimes with a managed web server. - [Learn more about Request Flow](/doc/develop/request-flow/) -- [Learn more about Varnish on Clever Cloud](/doc/develop/varnish/) +- [Learn more about Varnish on Clever Cloud](/doc/develop/request-flow/varnish/) +- [Learn more about OAuth2 Proxy on Clever Cloud](/doc/develop/request-flow/oauth2-proxy/) - [Learn more about Redirection.io](https://redirection.io/) diff --git a/shared/ruby.md b/shared/ruby.md index 21283d4d8..0232b7f1e 100644 --- a/shared/ruby.md +++ b/shared/ruby.md @@ -4,10 +4,10 @@ Be sure that: -* you push to the **master branch** -* you commit your `gems.locked` or `Gemfile.lock` file -* you have a `config.ru` file (this one is most of the time generated by rails) -* you have `gem puma` in your `Gemfile` (`puma` is the default application server from rails, when creating a new ruby application, an [environment variable](#setting-up-environment-variables-on-clever-cloud) is automatically added: `CC_RACKUP_SERVER=puma`) +- you push to the **master branch** +- you commit your `gems.locked` or `Gemfile.lock` file +- you have a `config.ru` file (this one is most of the time generated by rails) +- you have `gem puma` in your `Gemfile` (`puma` is the default application server from rails, when creating a new ruby application, an [environment variable](#setting-up-environment-variables-on-clever-cloud) is automatically added: `CC_RACKUP_SERVER=puma`) You need to provide a `gems.locked` or `Gemfile.lock` file. To do that ensure you have at least once run `bundle install` in your terminal at the root of your rails project. @@ -15,9 +15,9 @@ You need to provide a `gems.locked` or `Gemfile.lock` file. To do that ensure yo You can specify a Ruby version in your `gems.rb` or `Gemfile`, or set `CC_RUBY_VERSION=`, where `` can be, for example: -* "4" will select the greatest "4.x.y" version available. -* "4.0" will select the greatest "4.0.y" version available. -* "4.0.1" will select the "4.0.1" version. +- "4" will select the greatest "4.x.y" version available. +- "4.0" will select the greatest "4.0.y" version available. +- "4.0.1" will select the "4.0.1" version. If the given `` does not match any available version, your deployment will fail. If no version is specified, the latest 4.x version available on the image is used. Versions from the 4.x, 3.x and 2.x branches are available, but we recommend using an [officially supported version](https://www.ruby-lang.org/en/downloads/branches/). @@ -87,32 +87,20 @@ production: ### Manage your static files and assets -Static files are configured with [environment variables](#setting-up-environment-variables-on-clever-cloud): +For a Rails application using the asset pipeline, add `assets:precompile` to [`CC_RAKEGOALS`](#configure-rake-goals) so that assets are built during deployment. -`STATIC_FILES_PATH`: should point to a directory where your static files are stored. +Set `STATIC_FILES_PATH=public` to serve the generated files through NGINX consistently across Rails versions. Leave `STATIC_URL_PREFIX` unset for a standard Rails application. NGINX then serves common static file extensions from `public` and forwards other requests to Rails. -`STATIC_URL_PREFIX`: the URL path under which you want to serve static files (for example `/public/`) - -**Note**: the path of your folder must be absolute regarding the root of your application. - -**Note**: setting the `STATIC_URL_PREFIX` to `/` will make the deployment to fail. - -If you use the asset pipeline, make sure to include the `assets:precompile` task in the `CC_RAKEGOALS` environment variable value. - -```bash -CC_RAKEGOALS="db:migrate, assets:precompile" -``` - -**Note**: if your project uses `webpacker`, make sure to enable the dedicated build instance option in the **Information** menu of your application in the Clever Cloud console because `webpacker` needs a lot a resources when starting. +For other Rack applications, `STATIC_FILES_PATH` specifies the static files directory relative to the application root. You can optionally set `STATIC_URL_PREFIX` to expose these files under a specific URL path, such as `/assets`. Setting it to `/` makes NGINX look for every requested path in the static files directory before forwarding missing files to the application. ### Using Active Storage and Cellar S3 Only for Rails >= 5.2. -* Enable Active Storage for your application: `$ rails active_storage:install` then `$ rake db:migrate` -* Add `gem "aws-sdk-s3", require: false` to your Gemfile, run `$ bundle install` -* Add `config.active_storage.service = :clevercloud` in `config/environments/production.yml` -* Add in `config/storage.yml`: +- Enable Active Storage for your application: `$ rails active_storage:install` then `$ rake db:migrate` +- Add `gem "aws-sdk-s3", require: false` to your Gemfile, run `$ bundle install` +- Add `config.active_storage.service = :clevercloud` in `config/environments/production.yml` +- Add in `config/storage.yml`: ```yaml clevercloud: @@ -125,8 +113,8 @@ Only for Rails >= 5.2. force_path_style: true ``` -* In the clever cloud console create a Cellar S3 storage add-on, name it, link it to your rails application and create a bucket. -* In the environment variables section of your Ruby on Rails application on Clever Cloud add the following environment variables: +- In the clever cloud console create a Cellar S3 storage add-on, name it, link it to your rails application and create a bucket. +- In the environment variables section of your Ruby on Rails application on Clever Cloud add the following environment variables: ```bash CELLAR_ADDON_BUCKET_NAME="" @@ -136,27 +124,27 @@ Only for Rails >= 5.2. You can now commit and push your changes. Also, you are able to use a Filesystem Bucket to store your static files. Please refer to the -[File System Buckets](/doc/addons/fs-bucket) section. +[File System Buckets](/doc/deploy/storage/fs-bucket) section. ### NGINX configuration NGINX settings can be configured with [environment variables](#setting-up-environment-variables-on-clever-cloud): -* `NGINX_READ_TIMEOUT`: the response timeout in seconds. (Default: 300) +- `NGINX_READ_TIMEOUT`: the response timeout in seconds. (Default: 300) #### Basic authentication -If you need basic authentication, you can enable it using [environment variables](/doc/reference/reference-environment-variables/#ruby). You will need to set `CC_HTTP_BASIC_AUTH` variable to your own `login:password` pair. If you need to allow access to multiple users, you can create additional environment `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) variables. +If you need basic authentication, you can enable it using [environment variables](/doc/develop/common-configuration/environment-variables/reference/#ruby). You will need to set `CC_HTTP_BASIC_AUTH` variable to your own `login:password` pair. If you need to allow access to multiple users, you can create additional environment `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) variables. #### NGINX optional configuration with `clevercloud/http.json` NGINX settings can be configured further in `clevercloud/http.json`. All its fields are optional. -* `languages`: configure a default language and redirections -* `error_pages`: configure custom files for error pages -* `force_https`: automatically redirect HTTP traffic to HTTPS -* `aliases`: set up redirections -* `charset`: force a specific charset +- `languages`: configure a default language and redirections +- `error_pages`: configure custom files for error pages +- `force_https`: automatically redirect HTTP traffic to HTTPS +- `aliases`: set up redirections +- `charset`: force a specific charset ```json { @@ -182,8 +170,8 @@ Puma reads its configuration from the `config/puma.rb` file. See [the puma docum You can override this configuration with [environment variables](#setting-up-environment-variables-on-clever-cloud). Each of them, when specified, will be preferred over the setting from `config/puma.rb`. -* `CC_PUMA_WORKERS` overrides the number of workers (for example, `CC_PUMA_WORKERS=2`) -* `CC_PUMA_THREADS` overrides the number of threads per worker, can be a raw number or a range (for example, `CC_PUMA_THREADS=6` or `CC_PUMA_THREADS=4:8`) +- `CC_PUMA_WORKERS` overrides the number of workers (for example, `CC_PUMA_WORKERS=2`) +- `CC_PUMA_THREADS` overrides the number of threads per worker, can be a raw number or a range (for example, `CC_PUMA_THREADS=6` or `CC_PUMA_THREADS=4:8`) If they are not defined in the environment nor in `config/puma.rb` we will setup the values depending on the size of the scaler your application is running on. We also fill the `WEB_CONCURRENCY` and `RAILS_MAX_THREADS` environment variable if they are not present as they may be used by rails' puma configuration. diff --git a/shared/set-env-vars.md b/shared/set-env-vars.md index c22508bcc..3d1ab170c 100644 --- a/shared/set-env-vars.md +++ b/shared/set-env-vars.md @@ -10,9 +10,9 @@ ### With the Clever Tools CLI -1. Make sure you have clever-tools installed locally. Refer to our [CLI getting started](/doc/cli/). +1. Make sure you have clever-tools installed locally. Refer to our [CLI getting started](/doc/manage/cli/). 2. In your code folder, do `clever env set ` -Refer to [environment variables reference](/doc/reference/reference-environment-variables) for more details on available environment variables on Clever Cloud. +Refer to [environment variables reference](/doc/develop/common-configuration/environment-variables/reference) for more details on available environment variables on Clever Cloud. You can of course create custom ones with the interface we just demonstrated, they will be available for your application. diff --git a/shared/static-create.md b/shared/static-create.md index 70aef3ea9..d0b536b18 100644 --- a/shared/static-create.md +++ b/shared/static-create.md @@ -1,7 +1,7 @@ ## Deploy a static application -You can create an application in our [Console](https://console.clever-cloud.com) or through [Clever Tools](/doc/cli). Install them with `npm` or [any supported package manager](/doc/cli/install/): +You can create an application in our [Console](https://console.clever-cloud.com) or through [Clever Tools](/doc/manage/cli). Install them with `npm` or [any supported package manager](/doc/manage/cli/install/): ```bash # Install with npm or any supported method @@ -12,17 +12,15 @@ clever login clever profile ``` -Go to the folder where you want to create your application, and run the following command: +Go to the folder where you want to create your application, initialize a Git repository and create the linked application: ```bash cd myStaticApp -clever create -t static - -# If the folder is not a git repository, initialize it: git init +clever create -t static ``` -To deploy on Clever Cloud, your local folder need to be an initialized git repository linked to an application. If you already have an application on Clever Cloud and want to link it to the current local folder: +To deploy on Clever Cloud, your local folder needs to be an initialized Git repository linked to an application. If you already have an application on Clever Cloud and want to link it to the current local folder: ```bash clever link your_app_name_or_ID diff --git a/shared/static-deploy.md b/shared/static-deploy.md index d10988497..4da2f128d 100644 --- a/shared/static-deploy.md +++ b/shared/static-deploy.md @@ -5,6 +5,7 @@ Once you complete these steps, commit your content to the local repository and d ```bash git add . git commit -m "First deploy" + clever deploy clever open ``` @@ -18,4 +19,4 @@ clever domain add your.website.tld ### 404 page location -If you need to use a specific page for 404 errors, define its location with `SERVER_ERROR_PAGE_404` environment variable from Static Web Server, used as default in `static` runtime. For example : `SERVER_ERROR_PAGE_404=404.html`. +If you need to use a specific page for 404 errors, define its location with the `SERVER_ERROR_PAGE_404` environment variable from Static Web Server, used by default in the Static runtime. For example: `SERVER_ERROR_PAGE_404=404.html`. diff --git a/shared/static-guides.md b/shared/static-guides.md index 97e1ce716..b5f1a0c89 100644 --- a/shared/static-guides.md +++ b/shared/static-guides.md @@ -5,6 +5,7 @@ {{< card link="/developers/guides/hexo" title="Hexo" subtitle= "Build and deploy a static Hexo based website on Clever Cloud" icon="hexo" >}} {{< card link="/developers/guides/hugo" title="Hugo" subtitle= "Build and deploy a static Hugo based website on Clever Cloud" icon="hugo" >}} {{< card link="/developers/guides/lume-deno" title="Lume (Deno)" subtitle= "Build and deploy a static Lume (Deno) based website on Clever Cloud" icon="deno" >}} + {{< card link="/developers/guides/maudit" title="Maudit" subtitle= "Build and deploy a static Maudit website with Rust on Clever Cloud" icon="maudit" >}} {{< card link="/developers/guides/mdbook" title="mdBook" subtitle= "Build and deploy a static mbBook based website on Clever Cloud" icon="mdbook" >}} {{< card link="/developers/guides/mkdocs" title="MkDocs" subtitle= "Build and deploy a static MkDocs based website on Clever Cloud" icon="docs" >}} {{< card link="/developers/guides/nuxt" title="Nuxt" subtitle= "Build and deploy a Nuxt application on Clever Cloud" icon="nuxt" >}} diff --git a/shared/url_healthcheck.md b/shared/url_healthcheck.md index 138b58af6..0fcbc2946 100644 --- a/shared/url_healthcheck.md +++ b/shared/url_healthcheck.md @@ -17,7 +17,7 @@ CC_HEALTH_CHECK_PATH_1=/my/other/path The deployment process checks all paths. All of them must reply with a `200 OK` response code. -By default, when no [environment variable](/doc/reference/reference-environment-variables) (for ex: `APP_HOME`) is defined, the monitoring checks your repository root path `/`. +By default, when no [environment variable](/doc/develop/common-configuration/environment-variables/reference) (for ex: `APP_HOME`) is defined, the monitoring checks your repository root path `/`. ### Example diff --git a/shared/warp10-concepts.md b/shared/warp10-concepts.md index 65cce033d..379008e5d 100644 --- a/shared/warp10-concepts.md +++ b/shared/warp10-concepts.md @@ -6,5 +6,5 @@ A GeoTime Serie (GTS) is defined by a `class` and some `labels`. They're indexed Warp 10 uses Warp Script. It's a stack based language using reverse polish notation. -* [Warp 1O documentation](https://www.warp10.io/doc/reference) -* [Warp Script documentation](https://www.warp10.io/content/03_Documentation/04_WarpScript) +- [Warp 1O documentation](https://www.warp10.io/doc/tools/reference) +- [Warp Script documentation](https://www.warp10.io/content/03_Documentation/04_WarpScript) diff --git a/shared/warp10-content.md b/shared/warp10-content.md index 1087bfaaa..a66dde3ff 100644 --- a/shared/warp10-content.md +++ b/shared/warp10-content.md @@ -2,8 +2,8 @@ The platform's time unit is in **microsecond**. -* [Learn more about date functions](https://www.warp10.io/tags/date) -* [Learn more about time functions](https://www.warp10.io/tags/time) +- [Learn more about date functions](https://www.warp10.io/tags/date) +- [Learn more about time functions](https://www.warp10.io/tags/time) #### Duration is set by the followings symbols @@ -32,18 +32,18 @@ Builtin function: The followings limits are defined in Warp 10. The **soft** limit can be passed over by an [`AUTHENTICATE`](https://www.warp10.io/doc/AUTHENTICATE) operation. Operations over **soft limits** may be intensive. The **hard** limit is unsurpassable. -| WarpScript Operator | Warp 10 limit description | soft limit | hard limit | -| ------------------- | ------------------------------------------------------------- | ---------- | ---------- | -| MAXGTS | Maximum number of GTS which can be fetched | 10e5 | 5e7 | -| LIMIT | Maximum number of datapoints which can be fetched during a script execution | 10e6 | 10e7 | -| MAXBUCKETS | Maximum number of buckets which can be created by a call to BUCKETIZE | 10e5 | 50e5 | -| MAXDEPTH | Maximum depth (number of levels) of the execution stack | 5e3 | 5e3 | -| MAXLOOP | Maximum number of milliseconds which can be spent in a loop | 5e3 | 10e3 | -| MAXOPS | Maximum number of operations which can be performed during a single WarpScript execution | 5e6 | 5e7 | -| MAXSYMBOLS | Maximum number of simultaneous symbols which can be defined on the stack during a single WarpScript execution | 64 | 256 | -| MAXGEOCELLS | Maximum number of cells a GEOSHAPE | 10e3 | 10e4 | -| MAXPIXELS | Maximum size (in pixels) of images which can be created by PGraphics | 10e5 | 10e5 | -| MAXRECURSION | Maximum nesting depth of macro calls | 16 | 32 | +| WarpScript Operator | Warp 10 limit description | soft limit | hard limit | +| ------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | +| MAXGTS | Maximum number of GTS which can be fetched | 10e5 | 5e7 | +| LIMIT | Maximum number of datapoints which can be fetched during a script execution | 10e6 | 10e7 | +| MAXBUCKETS | Maximum number of buckets which can be created by a call to BUCKETIZE | 10e5 | 50e5 | +| MAXDEPTH | Maximum depth (number of levels) of the execution stack | 5e3 | 5e3 | +| MAXLOOP | Maximum number of milliseconds which can be spent in a loop | 5e3 | 10e3 | +| MAXOPS | Maximum number of operations which can be performed during a single WarpScript execution | 5e6 | 5e7 | +| MAXSYMBOLS | Maximum number of simultaneous symbols which can be defined on the stack during a single WarpScript execution | 64 | 256 | +| MAXGEOCELLS | Maximum number of cells a GEOSHAPE | 10e3 | 10e4 | +| MAXPIXELS | Maximum size (in pixels) of images which can be created by PGraphics | 10e5 | 10e5 | +| MAXRECURSION | Maximum nesting depth of macro calls | 16 | 32 | ### Usage @@ -68,13 +68,13 @@ It provides the path to the Clever Cloud Warp 10 gateway and let you explore you In Warp 10, classes organize metrics from various sources, like applications or add-ons, into specific categories (CPU usage, memory statistics, etc.). This structure makes the data easy to retrieve and analyze with WarpScript. -For a complete list of Telegraf classes and their descriptions, see [the classes list](/doc/metrics/#classes). +For a complete list of Telegraf classes and their descriptions, see [the classes list](/doc/develop/observability/metrics/#classes). ## Macro Warp 10 provide a server side macro manager. It is a way to release some ready to use WarpScript. Hence, Clever Cloud provides some macros as helpers to avoid redundant and often need code. -* [Warp 10' macros documentations](https://www.warp10.io/content/03_Documentation/07_Extending_Warp_10/01_Server_side_macros) +- [Warp 10' macros documentations](https://www.warp10.io/content/03_Documentation/07_Extending_Warp_10/01_Server_side_macros) ### Consumption diff --git a/static/cloud-synccloud-icon.png b/static/cloud-synccloud-icon.png deleted file mode 100644 index eb8f9f65f..000000000 Binary files a/static/cloud-synccloud-icon.png and /dev/null differ diff --git a/static/favicon.ico.png b/static/favicon.ico.png deleted file mode 100644 index b2ab15563..000000000 Binary files a/static/favicon.ico.png and /dev/null differ diff --git a/static/images/open_the_app_ico.png b/static/images/open_the_app_ico.png deleted file mode 100644 index d300ae966..000000000 Binary files a/static/images/open_the_app_ico.png and /dev/null differ diff --git a/static/images/pg-studio.png b/static/images/pg-studio.png deleted file mode 100644 index 188a9bfce..000000000 Binary files a/static/images/pg-studio.png and /dev/null differ diff --git a/update-cli-reference.sh b/update-cli-reference.sh index 1f7d1446b..23899dec7 100755 --- a/update-cli-reference.sh +++ b/update-cli-reference.sh @@ -23,6 +23,8 @@ aliases: - /reference/clever-tools - /reference/clever-tools/getting_started --- + + """ echo "${front_matter}" > "${FILE}"