doc: Add Markdown files

[wenzeslaus]

Following comments in #4620 (comment), here is a PR which does two things in two commits:

• Rename .html to .md
• Add .html files back

While the overall PR diff shows addition of .md files, the first commit itself shows rename and the second one addition. Both locally and on GitHub, blame for the .md files shows the history for the second commit, while for the .html file blame shows only one commit.

The idea id that we "Allow rebase merging" for couple minutes to merge this PR with its two commits.

Ideas? Feedback?

[echoix]

Rebase merge seems fine for me if it does a nice history

[wenzeslaus]

This is how I prepared the PR (updated):

git ls-files | grep -E ".html$" > ../all_html_files.txt

while read -r FILE; do git mv $FILE $(echo $FILE | sed -e 's+.html$+.md+g'); done < ../all_html_files.txt

Edit .markdownlint.yml, add:

# Errors from .html to .md rename (first step in HTML to Markdown conversion)
MD001: false # heading-increment
MD003: false # heading-style
MD004: false # ul-style
MD007: false # ul-indent
MD009: false # no-trailing-spaces
MD010: false # no-hard-tabs
MD011: false # no-reversed-links
MD012: false # no-multiple-blanks
MD013: false # line-length
MD018: false # no-missing-space-atx
MD019: false # no-multiple-space-atx
MD020: false # no-missing-space-closed-atx
MD022: false # blanks-around-headings
MD023: false # heading-start-left
MD024: false # no-duplicate-heading
MD026: false # no-trailing-punctuation
MD029: false # ol-prefix
MD032: false # blanks-around-lists
MD033: false # no-inline-html
MD034: false # no-bare-urls
MD037: false # no-space-in-emphasis
MD045: false # no-alt-text
MD049: false # emphasis-style
MD052: false # reference-links-images
MD055: false # table-pipe-style
MD058: false # blanks-around-tables
# The block above this is to be eventually removed.

git add -p

git commit -m "doc: Rename .html to .md

This is the first step in conversion of files with HTML documentation to Markdown.
It makes Git keep the history, esp. blame, for the Markdown file.
"

while read -r FILE; do cp $(echo $FILE | sed -e 's+.html$+.md+g') $FILE; git add $FILE; done < ../all_html_files.txt 

git commit -m "doc: Add .html files back

HTML will be in place as long as needed, but the primary, canonical file is the Markdown file.
"

[wenzeslaus]

It seems to work as desired for the history after a rebase merge. An example from my fork is here:

Blame on GitHub shows the "rich" history for .md:

https://github.com/wenzeslaus/grass/blame/experimental-main/db/databaseintro.md
https://github.com/wenzeslaus/grass/blame/experimental-main/db/databaseintro.html

Little less expected, but quite nice actually is the commit history where GitHub shows the rename for .md (with a link for more history) and the "rich" history for .html.

https://github.com/wenzeslaus/grass/commits/experimental-main/db/databaseintro.md
https://github.com/wenzeslaus/grass/commits/experimental-main/db/databaseintro.html

[echoix]

I like this, and shows the intent that the md files are the "canonical" version

[wenzeslaus]

In combination with #5048, this even produces an okayish mkdocs result.

Just for the record, I observed that d.background has Markdown syntax leaked to the resulting HTML while d.colorlist is okay. Not sure why that is, but it is not really important since the HTML in Markdown will be regenerated.

[wenzeslaus]

There are some linking issues in the "HTML-.md" files, so I will need to disable them with the first commit (now in a separate third commit - ignoring the merge commit which won't be in the final PR).

[neteler]

Looks like a good strategy, as discussed (I think) in Prague 2024 and subsequently.

[wenzeslaus]

I think I'm getting close here. If the Markdown lint passes, I will prepare the two actual commits.

[wenzeslaus]

This now depends on #5059 which is only waiting for CI to finish. (Only then I can prepare the final clean commits.)

[wenzeslaus]

This is now ready for review.

To merge, I will enable the Rebase and merge option and merge with that.