diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..c069b0605 --- /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 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 new file mode 100644 index 000000000..482018401 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,225 @@ +# 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. + +## 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 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: + +```yml +--- +title: What is Epoch +modified_at: 1970-01-01 00:00:00 +--- +``` + +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. 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. + +## 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. + +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` 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 + +If you want to write a useful note: + +```liquid +{% note %} + My useful note here +{% endnote %} +``` + +If you want to write a warning note: + +```liquid +{% 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 %}) +``` + +### 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: + +```liquid +{% assign img_url = "https://cdn.scalingo.com/documentation/screenshot_*" %} +{% include mdl_img.html %} +``` + +## Renaming a page + +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: + +- `_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. + +Example: + +```yml +"301": + - + old: "/old/path" + new: "/new/path" +``` + +## 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: + +```sh +docker compose -f docker compose-prod.yml up +``` + +This will run puma in parallel and serve the site at http://localhost:4302 + +### 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: + +```sh +docker compose exec web bundle exec jekyll build +``` + +### How to debug + +#### 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 + +#### 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. + +```liquid + {% include organisms/responsive_tool.html %} +``` + +#### Force regeneration + +Sometimes, the files regeneration (especially the assets) got lost. + +In this case remove the `_site` folder via +```sh +docker compose 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 +``` diff --git a/README.md b/README.md index b39bfe1a4..11576f0cd 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,50 @@ -# 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. +## Scalingo Getting Started -The minimal *front matter* that you need to add is: +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. -``` ---- -title: What is Epoch -modified_at: 2021-11-23 00:00:00 ---- -``` +Learn more about Scalingo on our website [https://scalingo.com](https://scalingo.com) -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 +## Documentation -## Modifying an article +This repository contains the source files for the Scalingo documentation. -You are welcome to modify any article, but please remember to update `modified_at` before sending your pull request. +To browse the live documentation, visit [https://doc.scalingo.com](https://doc.scalingo.com) -## 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. +## Repository Structure -Please do not use first-level HTML/Markdown headers (*i.e. `

`*) as it will be pulled from the `title ` metadata. +This repository is built with Jekyll. Beyond the technical directories related to configuration and site generation, the main content lives in: -__Blockquotes__ should be **only used for quotes**. +- [src/_posts/](./src/_posts/) for documentation pages +- [src/_tutorials/](./src/_tutorials/) for tutorials +- [src/changelog/](./src/changelog/) for changelog notes -Do not put `categories`, `category` or `permalink` in the *front matter*, everything is handled by the jekyll-dirname-generator plugin. -## Do's +## Contributing -If you want to write a useful note: +We welcome contributions to the Scalingo documentation and appreciate any help to improve it. -``` -{% 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)