Skip to content

Conversation

albertony
Copy link
Contributor

@albertony albertony commented Aug 24, 2025

This is a continuation of #8678, to make sure our Markdown docs uses a valid and consistent format. Here I've started to work through the command docs and backend docs, and have quite many issues, mostly things like this:

  • MD007/ul-indent: Unordered list indentation [Expected: 0; Actual: 2]
  • MD046/code-block-style: Code block style [Expected: fenced; Actual: indented]
  • MD040/fenced-code-language: Fenced code blocks should have a language specified
  • MD012/no-multiple-blanks: Multiple consecutive blank lines [Expected: 1; Actual: 2]
  • MD004/ul-style: Unordered list style [Expected: dash; Actual: asterisk]
  • MD032/blanks-around-lists: Lists should be surrounded by blank lines
  • MD013/line-length: Line length [Expected: 80; Actual: 153]

Since the files in focus this time are partially or entirely generated from source code, the process was to: build rclone, generate markdown, lint, fix issues in the sources of the markdown text, and repeat. This was done as a local and manual process for now, but the future plan is to get the linting of these running on GitHub pull requests alongside our other markdown linters, e.g. as I did a PoC on with #8704.

The work in this area is not done, but with these changes there are risk of git conflicts, so I wanted to ship a batch as soon as possible, and see if we are able to merge it before I continue with a new iteration. Also, I wanted to see the result of the checks for edits in autogenerated sections, that runs on the PR. I have run some tests locally, to look for any regressions in the command line help and the generated HTML pages, which are based on the same sources.

Next iteration (which I now plan as a new PR after this is merged) will start by going through the backend options - I've only updated the static parts of the backend docs so far in this PR.

Note that with the command docs, there is an issue with the cobra library we use, it generates parts of the markdown and currently the linter reports a couple of issues in that. I have changed it locally for now, to be able to lint the generated command docs without issues, but will have to think about what to do with this later.

What is the purpose of this change?

Was the change discussed in an issue or in the forum before?

Checklist

  • I have read the contribution guidelines.
  • I have added tests for all changes in this PR if appropriate.
  • I have added documentation for the changes if appropriate.
  • All commit messages are in house style.
  • I'm done, this Pull Request is ready for review :-)

@albertony albertony requested a review from ncw August 24, 2025 22:34
@albertony albertony self-assigned this Aug 24, 2025
@albertony albertony removed the request for review from ncw August 24, 2025 22:35
@albertony albertony force-pushed the lint-md branch 3 times, most recently from e70bfd0 to 9efba15 Compare August 24, 2025 23:13
@albertony albertony requested a review from ncw August 25, 2025 06:18
Copy link
Member

@ncw ncw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great - thanks @albertony

Please merge ASAP before it all bitrots!

@albertony
Copy link
Contributor Author

Thanks. Impressive catch with the two language tags - fixed them.

@albertony albertony merged commit adfe6b3 into rclone:master Aug 26, 2025
9 checks passed
@albertony albertony deleted the lint-md branch August 26, 2025 10:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants