From df772be57367fa3f242b781378a8dbeaef7f3607 Mon Sep 17 00:00:00 2001 From: Benjamin Date: Thu, 9 Apr 2026 15:55:46 +0200 Subject: [PATCH 01/12] Split the README into a general overview and move contribution guidelines to a separate CONTRIBUTING.md file. --- CONTRIBUTING.md | 130 ++++++++++++++++++++++++++++++++++++++++++ README.md | 147 +++++++++--------------------------------------- 2 files changed, 158 insertions(+), 119 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..4a003d6c5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# How to contribute + +[*Scalingo Documentation Center*](http://doc.scalingo.com) relies on Jekyll. You are welcome to contribute to this documentation by forking and sending pull requests. + +## Adding a new article + +To add a new article simply create a new markdown file in the `_posts` folder with the following file format: `yyyy-mm-dd-title.md` (*e.g. 1970-01-01-what-is-epoch.md*). +Please use the current date when creating the file. + +The minimal *front matter* that you need to add is: + +``` +--- +title: What is Epoch +modified_at: 2021-11-23 00:00:00 +--- +``` + +Optional tag : + +- `nav: [string]` set another url than the one generated from the title +- `index: [integer]` change the position of the page in his folder in the side menu + +## Modifying an article + +You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. + +## Don'ts + +Please do not use the `date` metadata as it will conflict with the date extracted from the file name. Instead, use `modified_at` to record when a modification is made to an article. + +Please do not use first-level HTML/Markdown headers (*i.e. `

`*) as it will be pulled from the `title ` metadata. + +__Blockquotes__ should be **only used for quotes**. + +Do not put `categories`, `category` or `permalink` in the *front matter*, everything is handled by the jekyll-dirname-generator plugin. + +## Do's + +If you want to write a useful note: + +``` +{% note %} + My useful note here +{% endnote %} +``` + +If you want to write a warning note: + +``` +{% warning %} + My warning note here +{% endwarning %} +``` + +If you want to insert a link to another documentation article: + +```markdown +[text of the link]({% post_url platform/internals/2000-01-01-routing %}) +``` + +To insert an image, first upload it to our CDN, inside the documentation +folder. Give it a public permission `Grant public read access to this +object(s)`. Then, insert it with: + +```liquid +{% assign img_url = "https://cdn.scalingo.com/documentation/screenshot_*" %} +{% include mdl_img.html %} +``` + +## Running Locally + +To install dependencies locally: + +```sh +docker compose build --pull \ +&& docker compose run --rm web bundle install \ +&& docker compose run --rm web yarn install --ignore-engines \ +&& docker compose run --rm web bundle exec jekyll build +``` + +To build the static site and spin-up a file server: + +```sh +docker compose up +``` + +And visit http://localhost:4300 + +If you want to serve the doc like in production (through the rack stack), generate the site first (see above) and then: + +``` +docker compose -f docker compose-prod.yml up +``` + +This will run puma in parallel and serve the site at http://localhost:4302 + +### Changelog, Samples and New Section + +For a reason I ignore and I don't want to spend time understanding, we need to manually re-build the pages when adding a new changelog entry or a new section. +This is done with: + +``` +docker compose exec web bundle exec jekyll build +``` + +### How to debug + +#### Ruby + +Using [debug.rb](https://github.com/ruby/debug) it's possible to add break points in Ruby code. +1. Prepend command `jekyll serve` by `rdbg -c -- ` +2. Add a `binding.break` where you want to stop the execution + +#### HTML/CSS + +To help debug responsive layout issues add this tool in the default layout, it will show the current Tailwind screen & size in every pages. + +``` + {% include organisms/responsive_tool.html %} +``` + +#### Force regeneration + +Sometimes, the files regeneration (especially the assets) got lost. + +In this case remove the `_site` folder via +``` +dc run web rm -rf _site +``` diff --git a/README.md b/README.md index b39bfe1a4..eaea6f8c1 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,43 @@ -# How to contribute +
+ + + + + Scalingo Logo + + -[*Scalingo Documentation Center*](http://doc.scalingo.com) relies on Jekyll. You are welcome to contribute to this documentation by forking and sending pull requests. +

Scalingo Documentation

-## Adding a new article + Documentation | + Tutorials | + Samples | + CLI | + Changelog | + API Reference +
-To add a new article simply create a new markdown file in the `_posts` folder with the following file format: `yyyy-mm-dd-title.md` (*e.g. 1970-01-01-what-is-epoch.md*). -Please use the current date when creating the file. -The minimal *front matter* that you need to add is: +## Scalingo Getting Started -``` ---- -title: What is Epoch -modified_at: 2021-11-23 00:00:00 ---- -``` +Scalingo is a European cloud platform designed to help teams deploy, run, and scale applications without the usual operational burden. We provide managed infrastructure and developer-focused services so companies can ship faster, stay focused on their product, and spend less time on painful Ops work. -Optional tag : +Learn more about Scalingo on our website [https://scalingo.com](https://scalingo.com) -- `nav: [string]` set another url than the one generated from the title -- `index: [integer]` change the position of the page in his folder in the side menu -## Modifying an article +## Documentation -You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. +This repository contains the source files for the Scalingo documentation. -## Don'ts +To browse the live documentation, visit [https://doc.scalingo.com](https://doc.scalingo.com). -Please do not use the `date` metadata as it will conflict with the date extracted from the file name. Instead, use `modified_at` to record when a modification is made to an article. +For LLM-oriented discovery and indexing, `llms.txt` is also available at: +[https://doc.scalingo.com/llms.txt](https://doc.scalingo.com/llms.txt) -Please do not use first-level HTML/Markdown headers (*i.e. `

`*) as it will be pulled from the `title ` metadata. -__Blockquotes__ should be **only used for quotes**. +## Contributing -Do not put `categories`, `category` or `permalink` in the *front matter*, everything is handled by the jekyll-dirname-generator plugin. +We welcome contributions to the Scalingo documentation and appreciate any help to improve it. -## Do's - -If you want to write a useful note: - -``` -{% note %} - My useful note here -{% endnote %} -``` - -If you want to write a warning note: - -``` -{% warning %} - My warning note here -{% endwarning %} -``` - -If you want to insert a link to another documentation article: - -```markdown -[text of the link]({% post_url platform/internals/2000-01-01-routing %}) -``` - -To insert an image, first upload it to our CDN, inside the documentation -folder. Give it a public permission `Grant public read access to this -object(s)`. Then, insert it with: - -```liquid -{% assign img_url = "https://cdn.scalingo.com/documentation/screenshot_*" %} -{% include mdl_img.html %} -``` - -## Running Locally - -To install dependencies locally: - -```sh -docker compose build --pull \ -&& docker compose run --rm web bundle install \ -&& docker compose run --rm web yarn install --ignore-engines \ -&& docker compose run --rm web bundle exec jekyll build -``` - -To build the static site and spin-up a file server: - -```sh -docker compose up -``` - -And visit http://localhost:4300 - -If you want to serve the doc like in production (through the rack stack), generate the site first (see above) and then: - -``` -docker compose -f docker compose-prod.yml up -``` - -This will run puma in parallel and serve the site at http://localhost:4302 - -### Changelog, Samples and New Section - -For a reason I ignore and I don't want to spend time understanding, we need to manually re-build the pages when adding a new changelog entry or a new section. -This is done with: - -``` -docker compose exec web bundle exec jekyll build -``` - -### How to debug - -#### Ruby - -Using [debug.rb](https://github.com/ruby/debug) it's possible to add break points in Ruby code. -1. Prepend command `jekyll serve` by `rdbg -c -- ` -2. Add a `binding.break` where you want to stop the execution - -#### HTML/CSS - -To help debug responsive layout issues add this tool in the default layout, it will show the current Tailwind screen & size in every pages. - -``` - {% include organisms/responsive_tool.html %} -``` - -#### Force regeneration - -Sometimes, the files regeneration (especially the assets) got lost. - -In this case remove the `_site` folder via -``` -dc run web rm -rf _site -``` - -## Links - -* [Scalingo Documentation Center](https://doc.scalingo.com) +- [Contribute to the documentation source](./CONTRIBUTING.md) +- [Suggest improvements or report issues](https://github.com/Scalingo/documentation/issues) From 3658465d8506a30002af33553c779b3e1bd7abd8 Mon Sep 17 00:00:00 2001 From: Benjamin Date: Thu, 9 Apr 2026 16:49:45 +0200 Subject: [PATCH 02/12] Add a filesystem overview to guide both humans and LLMs to the correct repository for browsing markdown content. --- README.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index eaea6f8c1..e3080f407 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,14 @@

Scalingo Documentation

- Documentation | - Tutorials | - Samples | - CLI | - Changelog | + Documentation | + Tutorials | + Samples | + CLI | + Changelog | API Reference - + ## Scalingo Getting Started @@ -35,6 +35,19 @@ For LLM-oriented discovery and indexing, `llms.txt` is also available at: [https://doc.scalingo.com/llms.txt](https://doc.scalingo.com/llms.txt) +## Repository Structure + +This repository is built with Jekyll and follows a mostly standard project structure. + +```text +Looking for something specific? +├─ Documentation source files → [src/](./src) +├─ Blog posts → [src/_posts/](./src/_posts/) +├─ Tutorials → [src/_tutorials/](./src/_tutorials/) +├─ Changelog notes → [src/changelog/](./src/changelog/) +``` + + ## Contributing We welcome contributions to the Scalingo documentation and appreciate any help to improve it. From b1e6c6be408a16d26e38a8ea72d037b3309e4126 Mon Sep 17 00:00:00 2001 From: Benjamin Date: Thu, 9 Apr 2026 17:03:22 +0200 Subject: [PATCH 03/12] Without code block --- README.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e3080f407..0e96a9af2 100644 --- a/README.md +++ b/README.md @@ -39,13 +39,11 @@ For LLM-oriented discovery and indexing, `llms.txt` is also available at: This repository is built with Jekyll and follows a mostly standard project structure. -```text -Looking for something specific? -├─ Documentation source files → [src/](./src) -├─ Blog posts → [src/_posts/](./src/_posts/) -├─ Tutorials → [src/_tutorials/](./src/_tutorials/) -├─ Changelog notes → [src/changelog/](./src/changelog/) -``` +- [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines +- [src/](./src) for the main documentation source files +- [src/_posts/](./src/_posts/) for blog posts +- [src/_tutorials/](./src/_tutorials/) for tutorials +- [src/changelog/](./src/changelog/) for changelog notes ## Contributing From c44c6707768c1568059a623f4c1fa1fa7202e732 Mon Sep 17 00:00:00 2001 From: Benjamin Date: Thu, 9 Apr 2026 17:11:53 +0200 Subject: [PATCH 04/12] Testing a more robust version of the header --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0e96a9af2..ba6253c62 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -
+

@@ -6,17 +6,18 @@ Scalingo Logo +

-

Scalingo Documentation

+

Scalingo Documentation

+

Documentation | Tutorials | Samples | CLI | Changelog | API Reference - -

+

## Scalingo Getting Started @@ -29,7 +30,7 @@ Learn more about Scalingo on our website [https://scalingo.com](https://scalingo This repository contains the source files for the Scalingo documentation. -To browse the live documentation, visit [https://doc.scalingo.com](https://doc.scalingo.com). +To browse the live documentation, visit [https://doc.scalingo.com](https://doc.scalingo.com) For LLM-oriented discovery and indexing, `llms.txt` is also available at: [https://doc.scalingo.com/llms.txt](https://doc.scalingo.com/llms.txt) From 120d920b08c2725e0f11b4c05b18bd1832e574d9 Mon Sep 17 00:00:00 2001 From: Benjamin Date: Fri, 10 Apr 2026 09:35:11 +0200 Subject: [PATCH 05/12] New logo urls --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ba6253c62..c2935f39e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@

- - - Scalingo Logo + + + Scalingo Logo

From 2a7e7f8f79e1f63263a3ceb8958b693f2105709f Mon Sep 17 00:00:00 2001 From: Benjamin Date: Fri, 10 Apr 2026 09:36:05 +0200 Subject: [PATCH 06/12] Inverse logo color scheme logic --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c2935f39e..82d2f0294 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@

- - - Scalingo Logo + + + Scalingo Logo

From b9f6ad695a7770bdae66adb03aba67ca98e997b6 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Fri, 10 Apr 2026 12:58:31 +0200 Subject: [PATCH 07/12] docs: clarify contribution guidelines and trim AGENTS.md --- AGENTS.md | 16 ++++++++ CONTRIBUTING.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 109 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..fcdd5e351 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# AGENTS.md + +This repository contains the Scalingo Documentation Center. + +Before making changes, read: + +- `README.md` for repository context and structure +- `CONTRIBUTING.md` for contribution rules, content conventions, redirects, and validation steps + +Agent-specific guidance: + +- Keep edits minimal and scoped to the user request. +- Do not duplicate rules from `README.md` or `CONTRIBUTING.md` here. +- Prefer updating canonical documentation rather than adding new local instructions. +- When moving or renaming documentation pages, update internal links in the same change. +- If a repository rule conflicts with an explicit user request, follow the user request. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a003d6c5..1f1195b22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,10 +2,25 @@ [*Scalingo Documentation Center*](http://doc.scalingo.com) relies on Jekyll. You are welcome to contribute to this documentation by forking and sending pull requests. +## Repository structure + +Jekyll reads its source files from `src/` because `_config.yml` sets `source: src`. + +Main content is organized in: + +- `src/_posts/` for documentation pages +- `src/_tutorials/` for tutorials +- `src/_tutorials_categories/` for tutorial categories +- `src/changelog/` for changelog entries +- `src/_includes/` for reusable Liquid partials +- `assets/` for source assets +- `src/assets/` for built assets + ## Adding a new article -To add a new article simply create a new markdown file in the `_posts` folder with the following file format: `yyyy-mm-dd-title.md` (*e.g. 1970-01-01-what-is-epoch.md*). +To add a new content page, create a new markdown file in the appropriate directory for that content type, using the following file format: `yyyy-mm-dd-title.md` (*e.g. 1970-01-01-what-is-epoch.md*). Please use the current date when creating the file. +The date in the filename must be less than or equal to the current build date, otherwise the page may be excluded from the build output. The minimal *front matter* that you need to add is: @@ -16,14 +31,32 @@ modified_at: 2021-11-23 00:00:00 --- ``` -Optional tag : +Optional tags: - `nav: [string]` set another url than the one generated from the title - `index: [integer]` change the position of the page in his folder in the side menu +- `tags: [string]` add search and classification keywords +- `layout: [string]` use a specific page layout for special pages +- `description: [string]` add a short page description used by some landing pages +- `subnav_index: [integer]` set the position of a page in the sub-navigation +- `logo: [string]` define the icon or logo used by tutorial pages +- `products: [array]` list related Scalingo products for a tutorial +- `category: [string]` assign a tutorial to a tutorial category +- `permalink: [string]` define the public URL of tutorials and other special pages that require a stable path +- `is_series: [boolean]` mark a tutorial as part of a series +- `series: [string]` group tutorial pages under the same series name +- `series_index: [integer]` set the position of a page inside a tutorial series +- `oses: [array]` list supported operating systems on pages that display OS-specific icons +- `cvss: [object]` define CVSS metadata for security bulletins +- `github: [string]` link a changelog entry to the upstream GitHub repository + +The exact set of supported tags depends on the content type and layout. When in doubt, copy the front matter structure from a nearby page of the same kind. ## Modifying an article -You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. +You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. In existing content, `modified_at` is typically set to `09:00:00`; prefer keeping that convention unless you have a reason to do otherwise. + +When adding or editing content, prefer following the existing structure and naming conventions used by nearby files. ## Don'ts @@ -33,7 +66,9 @@ Please do not use first-level HTML/Markdown headers (*i.e. `

`*) as it w __Blockquotes__ should be **only used for quotes**. -Do not put `categories`, `category` or `permalink` in the *front matter*, everything is handled by the jekyll-dirname-generator plugin. +Do not put `categories` in the *front matter*. Avoid adding `category` or `permalink` to regular documentation pages in `src/_posts/` unless the content type already relies on them, such as tutorials or some legacy pages. + +Do not manually edit generated files in `src/assets/` unless the task explicitly requires it. Prefer editing the source files in `assets/`. ## Do's @@ -59,6 +94,28 @@ If you want to insert a link to another documentation article: [text of the link]({% post_url platform/internals/2000-01-01-routing %}) ``` +## Links + +Prefer reference-style Markdown links when a page contains several links or when the target URL is long. + +Example in content: + +```markdown +Open your [account dashboard][dashboard]. +Transfer ownership with [this guide][transfer-project-ownership]. +``` + +Then define the links at the bottom of the page: + +```markdown +[dashboard]: https://dashboard.scalingo.com/ +[transfer-project-ownership]: {% post_url platform/projects/2000-01-01-manage-projects %}#transfer-project-ownership +``` + +This keeps the body of the page easier to read and makes link maintenance simpler. + +For short, isolated links, inline Markdown links are still acceptable. + To insert an image, first upload it to our CDN, inside the documentation folder. Give it a public permission `Grant public read access to this object(s)`. Then, insert it with: @@ -68,6 +125,23 @@ object(s)`. Then, insert it with: {% include mdl_img.html %} ``` +## Redirects + +Redirects are defined in `redirections.yml`. + +If you rename a page or change its path, add a new redirect entry in the `301` section in the same change. + +New redirect entries must be inserted above the `obsolete` section. Existing redirect entries should not be rewritten, reordered or removed as part of a normal page move. + +Example: + +```yml +"301": + - + old: "/old/path" + new: "/new/path" +``` + ## Running Locally To install dependencies locally: @@ -128,3 +202,18 @@ In this case remove the `_site` folder via ``` dc run web rm -rf _site ``` + +## Validation + +After content or configuration changes, run: + +```sh +docker compose run --rm web bundle exec jekyll build +``` + +After asset changes, run: + +```sh +docker compose run --rm web yarn build +docker compose run --rm web bundle exec jekyll build +``` From ef22f89c46e9de3949ff4b0e0359a791ed9a7732 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Fri, 10 Apr 2026 15:52:46 +0200 Subject: [PATCH 08/12] Clarify page rename maintenance steps --- CONTRIBUTING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f1195b22..3053bc43f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,11 +125,15 @@ object(s)`. Then, insert it with: {% include mdl_img.html %} ``` -## Redirects +## Renaming a page -Redirects are defined in `redirections.yml`. +If you rename a page or change its path, check the root-level files that may contain hardcoded internal URLs or routing rules related to that page, especially: -If you rename a page or change its path, add a new redirect entry in the `301` section in the same change. +- `_config.yml` +- `config.ru` +- `redirections.yml` + +If the public URL changes, add a new redirect entry in the `301` section of `redirections.yml` in the same change. New redirect entries must be inserted above the `obsolete` section. Existing redirect entries should not be rewritten, reordered or removed as part of a normal page move. From dbb42f66f1b8639cb297d198562d53132761b2d4 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Fri, 10 Apr 2026 18:35:02 +0200 Subject: [PATCH 09/12] Clarify README repository structure --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 82d2f0294..a1a2fb56f 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,9 @@ For LLM-oriented discovery and indexing, `llms.txt` is also available at: ## Repository Structure -This repository is built with Jekyll and follows a mostly standard project structure. +This repository is built with Jekyll. Beyond the technical directories related to configuration and site generation, the main content lives in: -- [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines -- [src/](./src) for the main documentation source files -- [src/_posts/](./src/_posts/) for blog posts +- [src/_posts/](./src/_posts/) for documentation pages - [src/_tutorials/](./src/_tutorials/) for tutorials - [src/changelog/](./src/changelog/) for changelog notes From 17e6d5541c0112abb143b1104a7cd2d2297245d2 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Fri, 10 Apr 2026 18:46:17 +0200 Subject: [PATCH 10/12] docs: clarify contribution headings and examples --- CONTRIBUTING.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3053bc43f..9d92e427a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ The minimal *front matter* that you need to add is: ``` --- title: What is Epoch -modified_at: 2021-11-23 00:00:00 +modified_at: 1970-01-01 00:00:00 --- ``` @@ -58,7 +58,9 @@ You are welcome to modify any article, but please remember to update `modified_a When adding or editing content, prefer following the existing structure and naming conventions used by nearby files. -## Don'ts +## Content conventions + +### Don'ts Please do not use the `date` metadata as it will conflict with the date extracted from the file name. Instead, use `modified_at` to record when a modification is made to an article. @@ -70,7 +72,7 @@ Do not put `categories` in the *front matter*. Avoid adding `category` or `perma Do not manually edit generated files in `src/assets/` unless the task explicitly requires it. Prefer editing the source files in `assets/`. -## Do's +### Do's If you want to write a useful note: @@ -94,7 +96,7 @@ If you want to insert a link to another documentation article: [text of the link]({% post_url platform/internals/2000-01-01-routing %}) ``` -## Links +### Links Prefer reference-style Markdown links when a page contains several links or when the target URL is long. @@ -140,7 +142,6 @@ New redirect entries must be inserted above the `obsolete` section. Existing red Example: ```yml -"301": - old: "/old/path" new: "/new/path" @@ -173,7 +174,7 @@ docker compose -f docker compose-prod.yml up This will run puma in parallel and serve the site at http://localhost:4302 -### Changelog, Samples and New Section +### Manual rebuilds for changelog, samples, and new sections For a reason I ignore and I don't want to spend time understanding, we need to manually re-build the pages when adding a new changelog entry or a new section. This is done with: @@ -184,13 +185,13 @@ docker compose exec web bundle exec jekyll build ### How to debug -#### Ruby +#### Jekyll build Using [debug.rb](https://github.com/ruby/debug) it's possible to add break points in Ruby code. 1. Prepend command `jekyll serve` by `rdbg -c -- ` 2. Add a `binding.break` where you want to stop the execution -#### HTML/CSS +#### Theming (HTML/CSS) To help debug responsive layout issues add this tool in the default layout, it will show the current Tailwind screen & size in every pages. From 18249f0969f21f7e17e673f1e39c71aea019d721 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Fri, 10 Apr 2026 18:52:59 +0200 Subject: [PATCH 11/12] docs: clarify contributing guide structure --- CONTRIBUTING.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d92e427a..dbec3561e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ The date in the filename must be less than or equal to the current build date, o The minimal *front matter* that you need to add is: -``` +```yml --- title: What is Epoch modified_at: 1970-01-01 00:00:00 @@ -76,7 +76,7 @@ Do not manually edit generated files in `src/assets/` unless the task explicitly If you want to write a useful note: -``` +```liquid {% note %} My useful note here {% endnote %} @@ -84,7 +84,7 @@ If you want to write a useful note: If you want to write a warning note: -``` +```liquid {% warning %} My warning note here {% endwarning %} @@ -142,6 +142,7 @@ New redirect entries must be inserted above the `obsolete` section. Existing red Example: ```yml +"301": - old: "/old/path" new: "/new/path" @@ -168,7 +169,7 @@ And visit http://localhost:4300 If you want to serve the doc like in production (through the rack stack), generate the site first (see above) and then: -``` +```sh docker compose -f docker compose-prod.yml up ``` @@ -179,7 +180,7 @@ This will run puma in parallel and serve the site at http://localhost:4302 For a reason I ignore and I don't want to spend time understanding, we need to manually re-build the pages when adding a new changelog entry or a new section. This is done with: -``` +```sh docker compose exec web bundle exec jekyll build ``` @@ -195,7 +196,7 @@ Using [debug.rb](https://github.com/ruby/debug) it's possible to add break point To help debug responsive layout issues add this tool in the default layout, it will show the current Tailwind screen & size in every pages. -``` +```liquid {% include organisms/responsive_tool.html %} ``` @@ -204,8 +205,8 @@ To help debug responsive layout issues add this tool in the default layout, it w Sometimes, the files regeneration (especially the assets) got lost. In this case remove the `_site` folder via -``` -dc run web rm -rf _site +```sh +docker compose run web rm -rf _site ``` ## Validation From f4f3a5413e3b194be0b35ebfc7a9366c7c8fc32e Mon Sep 17 00:00:00 2001 From: Benjamin Date: Wed, 15 Apr 2026 09:41:20 +0200 Subject: [PATCH 12/12] Address Etienne's review comments --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 3 --- 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fcdd5e351..c069b0605 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,5 +12,5 @@ Agent-specific guidance: - Keep edits minimal and scoped to the user request. - Do not duplicate rules from `README.md` or `CONTRIBUTING.md` here. - Prefer updating canonical documentation rather than adding new local instructions. -- When moving or renaming documentation pages, update internal links in the same change. +- When moving or renaming documentation pages, update internal links and add the corresponding redirect in redirections.yml in the same change. - If a repository rule conflicts with an explicit user request, follow the user request. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbec3561e..482018401 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,7 +54,7 @@ The exact set of supported tags depends on the content type and layout. When in ## Modifying an article -You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. In existing content, `modified_at` is typically set to `09:00:00`; prefer keeping that convention unless you have a reason to do otherwise. +You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. In existing content, `modified_at` is typically set to `00:00:00`; prefer keeping that convention unless you have a reason to do otherwise. When adding or editing content, prefer following the existing structure and naming conventions used by nearby files. diff --git a/README.md b/README.md index a1a2fb56f..11576f0cd 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,6 @@ This repository contains the source files for the Scalingo documentation. To browse the live documentation, visit [https://doc.scalingo.com](https://doc.scalingo.com) -For LLM-oriented discovery and indexing, `llms.txt` is also available at: -[https://doc.scalingo.com/llms.txt](https://doc.scalingo.com/llms.txt) - ## Repository Structure