Skip to content

Converted the readme to markdown for accessibility - #362

Merged
dstelzer merged 2 commits into
Dialog-IF:mainfrom
eigencrow:markdown-readme
Sep 28, 2026
Merged

dstelzer merged 2 commits into
Dialog-IF:mainfrom
eigencrow:markdown-readme

Conversation

@eigencrow

Copy link
Copy Markdown
Contributor

Plain text files are difficult to skim with a screenreader, because they contain no semantic information. A readme is the type of file one often needs to skim, to find platform-specific build instructions, website links, release notes, etc. Because markdown can be rendered as semantic HTML, it is inherently more accessible to screenreaders, and possibly more user friendly to those less familiar with GitHub. I manually converted the whole repo readme to markdown, flattening indented lines according to the style I know and use. The biggest changes are turning the section titles into headings, and making the directory structure into a table.

I used minimal emphasis, partly to avoid the LLM flavor, mostly because it was plain text to begin with and I didn't want to unintentionally change any meanings. I only emphasized text where a previously indented line seemed to be doing so.

I didn't format the release notes at all, beyond giving each version a heading at level 3, and Linus's library bugfixes/releases at level 4. This is for the reasons already mentioned, and also because it's a lot of text to format by hand, although I want to for completionist reasons. I do think the release notes would be better off in a separate document, linked to by the readme, but that's an issue for another issue.

… notes, which are only divided into headings for now
@dstelzer

Copy link
Copy Markdown
Contributor

This all looks good to me! The one change I'd request is adding a line to the changelog mentioning converting the README to Markdown.

@eigencrow

Copy link
Copy Markdown
Contributor Author

Done! I classified it as "Documentation" as I wasn't sure what else it should be. Lemme know if that's wrong. :7

@dstelzer

Copy link
Copy Markdown
Contributor

Looks good to me!

@dstelzer
dstelzer merged commit 089ed85 into Dialog-IF:main Sep 28, 2026
5 checks passed
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