Tons of Markdown fixes, improvements, and cleanup #151
Conversation
Before, empty anchor tags with name attributes were placed before headings, so other anchor tags could target and automatically scroll to the heading when clicked. However, this functionality can and should be implemented by giving the headings ID attributes instead. This is more concise, easier to maintain, and a more proper use of HTML5.
Markdown syntax is more concise and should be preferred over inline HTML.
Many of the headings on the website were broken, as many of the headings lacked a space after the hashtags, which many Markdown renderers require.
Markdown syntax is more concise and should be preferred over inline HTML.
Markdown syntax is more concise and should be preferred over inline HTML.
Markdown syntax is more concise and should be preferred over inline HTML.
Markdown ignores more than 2 newlines in a row.
Standardized number of dots in ellipses and surrounding spacing.
Removed spaces, added colons, and capitalized where necessary.
Markdown headings should be followed by 1 blank line, especially before indented code blocks.
Markdown list delimiters need only be followed by one space.
Replaced repeated hyphens and asterisks with triple hyphens. Replaced triple hyphens after a heading with more traditional Markdown headings. Replaced triple tildes for code blocks with triple backticks.
Made ordered list delimiters sequential. Converted unordered list delimiters to asterisks. Made quotation list citation scheme consistent across languages.
|
Thanks for the contribution. Is it finished? Out of curiosity, did you fix them manually or using a command line tool? |
|
Pull requests that touch 100+ files always scare me as a reviewer but this looks good at first glance. |
|
@cclauss Haha that's understandable, so sorry about that! You don't have to accept it if you don't feel comfortable! I just had free time on my hands and came across the documentation when cataloging Python web frameworks. @iredmail It was assisted manual. For the majority of the replacements, I wrote regular expressions in VSCode's Find and Replace fields, but instead of pushing "Replace All," I went through each proposed replacement (or sometimes file-by-file), looking it over and accepting or denying it. This was to avoid replacing inside code blocks or other ambiguous cases. When in doubt, I left it alone and denied the change. I avoided a few files, like api.md, that I suspected were automatically generated HTML. I'm hoping it's finished! I don't want to be too perfectionist. There are probably more issues lying around, but I cut myself off here. |
These changes massively improve the Markdown files, both for people browsing the live website and the GitHub repository.
For people browsing the live website, the changes fix the widespread problem of Markdown headings not rendering, as well as generally reducing awkward inconsistencies like extra spacing around punctuation, or too many/few dots in ellipses (...).
For people browsing or contributing to the GitHub repository, the changes also make the Markdown files more consistent with each other and with commonly accepted Markdown conventions, which makes it more straightforward for future contributors to analyze and edit them.
I've tried to explain my reasoning behind each commit in their descriptions.