Skip to content

"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files

docs: update contributing guide regarding markdown documentation

albertony122890799fb9
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