Open mdsanima opened 1 week ago
Ah, nice, ...
I guess you are still working on this? Do you give me a signal when I should have a look? :-)
I'm working on it right now. These two files are enough for initial configuration. I think it would be good to add the configuration file to the editor as well. Now I'm doing formatting on all the markdown files in the project and checking if everything is correct.
Sure, I'll let you know today so you can check.
I think it would also be good to organize the names of Markdown files, especially the main readme.md file, which according to standards should be named with capital letters.
If the file is named in uppercase, it is more visible and displayed as one of the first in the list in the editor. The same applies in the terminal.
I think it would be appropriate to first rename with this git mv readme.md README.md
command, and then format the document. The same applies to the all other translation files.
@Finii do you have any objections to me making this change? Pleas, let me know! Thanks!
@allcontributors please add @mdsanima for maintenance
@Finii
I've put up a pull request to add @mdsanima! :tada:
I think it would also be good to organize the names of Markdown files, especially the main readme.md file, which according to standards should be named with capital letters.
Of course the is no such standard, it is just a custom from ancient times - I remember pulling packets from the local BBS and unpacking those, and the most relevant documentation was in CAPS named files to find them quickly.
I think (hope) I changed all readmes in the meantime to README.md
, and if you still find some 'wrong' ones I believe they should be renamed. I remember we also had readme.txt and readme.rst :thinking:
Ah, yes, here they are:
bin/scripts/standardize-and-complete-readmes.sh
mapfile -t RST < <(find "$searchdir" -type f -iname 'readme.rst')
mapfile -t TXT < <(find "$searchdir" -type f -iname 'readme.txt')
mapfile -t MD < <(find "$searchdir" -type f -iname 'readme.md')
We did use pandoc
to convert the rst
s, but I believe we have no rst
anymore anyhow and that conversion is not needed.
But this should probably also be changed to CAPs:
bin/scripts/archive-font-patcher.sh
mini_readme="$outputdir/readme.md"
But I would leave the 'root' readme*.md
lowercase for these reasons:
I think it would be good to add the configuration file to the editor as well.
Well, I edit with neovim
and it has some rudimentary rendering and checks; and occasionally I get confused because Github's md
is different from Gitlab's md
and I edit both multiple times a day :grimacing:
I would just add the linter to the CI so that any changes will be checked and reported, so that authors can adapt their PRs accordingly. Like we do with shellcheck
. I can do that easily after this PR is pulled.
I did not test how markdownlint
fares with the partial md files we have to assemble the final texts, like /src/readme-per-directory-addendum.md
:thinking:
Edit: Correct typo and improve formatting
Thanks for your patience, I had a few other tasks to do in the meantime, but now I'm back to this.
Ok, I think this can be checked now, in the next pull request I will add formatting.
- This is usually looked at in the browser and shown by Github per default anyhow on the main page
- If someone clones the repo and wants to do something with it that readme is more or less useless
The default README.md file on GitHub is created in uppercase when you create a new repository.
Do you give me a signal when I should have a look? :-)
Hello @Finii, I think this is ready for the reviews.
Added
.markdownlint.yml
and.prettierrc
configuration files to establish and maintain uniform coding and Markdown styling conventions across the project.These configurations enforce rules such as consistent line lengths, the use of semi-colons, and the handling of inline HTML and link fragments in Markdown, ensuring readable and maintainable documentation and codebase. Moreover, revised the
CHANGELOG.md
section header in.versionrc
for better clarity and readability, aligning with markdownlint's recommendations.This initiative aims to minimize style discrepancies and improve code readability, facilitating a smoother collaboration process. It is an essential step towards a more structured and efficient development workflow, acknowledging that consistency is key to a project's long-term success.
Related: #1665
Requirements / Checklist