Skip to content

Conversation

bittner
Copy link

@bittner bittner commented Apr 25, 2025

Linters like PyMarkdown complain about the license comment starting Markdown documents.

README.md:1:1: MD041: First line in file should be a top level heading (first-line-heading,first-line-h1)

While the reuse tool still puts the license comment in line 1, we can showcase in this repository how to handle this situation through manual editing to both please the linter and stay REUSE-compliant.

This change relates to the discussion in issue #868.

  • Added a change log entry in changelog.d/<directory>/.
  • Added self to copyright blurb of touched files.
  • Added self to AUTHORS.rst. **)
  • Wrote tests.
  • Documented my changes in docs/man/ or elsewhere.
  • My changes do not contradict the current specification.
  • I agree to license my contribution under the licenses indicated in the changed files.

**) As this is a trivial change, I waive my right to be credited as an author.

Linters like PyMarkdown complain about the license comment starting Markdown documents.  While the `reuse` tool still puts the license comment in line 1, we can showcase in this repository how to handle this situation through manual editing to both please the linter and stay REUSE-compliant.

Related to the discussion in issue fsfe#868.
@floriansnow
Copy link
Contributor

Thank you very much for your contribution! I like your idea of showcasing how you can achieve compatibility with both tools here. However, I don't think the specific solution is very nice. Starting with this heading just to please the linter when in fact a comment is not a crazy first line to have, looks hacky to me. It doesn't look like it's going to be fixed in pymarkdown and their recommendation is to adjust the config. We can try giving some more feedback there, but if that doesn't help, I think ignoring the (invalid) complaint from pymarkdown is best. WDYT?

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