From 122890799fb9e2ff0bc74e858d7e863b22c7359f Mon Sep 17 00:00:00 2001
From: albertony <12441419+albertony@users.noreply.github.com>
Date: Sun, 13 Jul 2025 23:13:07 +0200
Subject: [PATCH] docs: update contributing guide regarding markdown
 documentation

---
 CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 46 insertions(+), 13 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b711e4377..781f7e8ed 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -306,8 +306,10 @@ with modules beneath.
   - ...commands
 - cmdtest - end-to-end tests of commands, flags, environment variables,...
 - docs - the documentation and website
-  - content - adjust these docs only - everything else is autogenerated
-  - command - these are auto-generated - edit the corresponding .go file
+  - content - adjust these docs only, except those marked autogenerated
+    or portions marked autogenerated where the corresponding .go file must be
+    edited instead, and everything else is autogenerated
+    - commands - these are auto-generated, edit the corresponding .go file
 - fs - main rclone definitions - minimal amount of code
   - accounting - bandwidth limiting and statistics
   - asyncreader - an io.Reader which reads ahead
@@ -345,6 +347,36 @@ with modules beneath.
 
 If you are adding a new feature then please update the documentation.
 
+The documentation sources are generally in Markdown format, in conformance
+with the CommonMark specification and compatible with GitHub Flavored
+Markdown (GFM). The markdown format is checked as part of the lint operation
+that runs automatically on pull requests, to enforce standards and consistency.
+This is based on the [markdownlint](https://github.com/DavidAnson/markdownlint)
+tool, which can also be integrated into editors so you can perform the same
+checks while writing.
+
+HTML pages, served as website <rclone.org>, are generated from the Markdown,
+using [Hugo](https://gohugo.io). Note that when generating the HTML pages,
+there is currently used a different algorithm for generating header anchors
+than what GitHub uses for its Markdown rendering. For example, in the HTML docs
+generated by Hugo any leading `-` characters are ignored, which means when
+linking to a header with text `--config string` we therefore need to use the
+link `#config-string` in our Markdown source, which will not work in GitHub's
+preview where `#--config-string` would be the correct link.
+
+Most of the documentation are written directly in text files with extension
+`.md`, mainly within folder `docs/content`. Note that several of such files
+are autogenerated (e.g. the command documentation, and `docs/content/flags.md`),
+or contain autogenerated portions (e.g. the backend documentation under
+`docs/content/commands`). These are marked with an `autogenerated` comment.
+The sources of the autogenerated text are usually Markdown formatted text
+embedded as string values in the Go source code, so you need to locate these
+and edit the `.go` file instead. The `MANUAL.*`, `rclone.1` and other text
+files in the root of the repository are also autogenerated. The autogeneration
+of files, and the website, will be done during the release process. See the
+`make doc` and `make website` targets in the Makefile if you are interested in
+how. You don't need to run these when adding a feature.
+
 If you add a new general flag (not for a backend), then document it in
 `docs/content/docs.md` - the flags there are supposed to be in
 alphabetical order.
@@ -373,19 +405,20 @@ the source file in the `Help:` field.
     create a new list item. Also, for enumeration texts like name of
     countries, it looks better without an ending period/full stop character.
 
-The only documentation you need to edit are the `docs/content/*.md`
-files.  The `MANUAL.*`, `rclone.1`, website, etc. are all auto-generated
-from those during the release process.  See the `make doc` and `make
-website` targets in the Makefile if you are interested in how.  You
-don't need to run these when adding a feature.
+When writing documentation for an entirely new backend,
+see [backend documentation](#backend-documentation).
 
-Documentation for rclone sub commands is with their code, e.g.
-`cmd/ls/ls.go`. Write flag help strings as a single sentence on a single
-line, without a period/full stop character at the end, as it will be
-combined unmodified with other information (such as any default value).
+If you are updating documentation for a command, you must do that in the
+command source code, e.g. `cmd/ls/ls.go`. Write flag help strings as a single
+sentence on a single line, without a period/full stop character at the end,
+as it will be combined unmodified with other information (such as any default
+value).
 
-Note that you can use [GitHub's online editor](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository)
-for small changes in the docs which makes it very easy.
+Note that you can use
+[GitHub's online editor](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository)
+for small changes in the docs which makes it very easy. Just remember the
+caveat when linking to header anchors, noted above, which means that GitHub's
+Markdown preview may not be an entirely reliable verification of the results.
 
 ## Making a release