-
Notifications
You must be signed in to change notification settings - Fork 323
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore: rename markdown doc for convenient browsing #80
Conversation
Thanks for the PR. Is it the case that you would broadly want this kind of effect (i.e. GitHub rendering) for all files named If so, I'd like to ask GitHub to add the feature for everyone. This is because there are a bunch of files like this, such as thousands of blogs, that all use *.md files, that could benefit from automatic rendering. |
I don't think there needs to be any changes on GitHub's end. For consistency, the convention is that only What if there is a directory with both Or if someone doesn't want their markdown to render for whatever reason, that could be a breaking change for them. I think rendering any markdown file would cause more confusion than it would solve. Especially when people can achieve the desired goal by naming their file-to-render |
Yes, that's the problem here. What you're describing is what Microsoft is trying to change because of bias. What you're seeing is the effect of Microsoft's employees applying a set of their own internal non-standard rules to one kind of filename, rather than using any open standard or enabling an open source author to choose the outcome. Microsoft is actively aiming to change the bias going forward. This is because the bias causes problematic issues for repositories that need to work across a variety of systems, such as for Microsoft enterprise customers, especially ones with legal/political/organizational/technical needs for specific files and file names. Some examples are creators of repos who want to use non-English languages, or who want readme.md rendered as markdown not as GitHub Flavored Markdown, or who want to use non-Microsoft formats or markdown adjucnts. The best solution (IMHO) is to have developers who care enabled to make their own choices about rendering. This is where Microsoft leaders want to head because it's better for inter-organizational teams and diverse enterprises such as multi-national companies.
The index.md file. When a user goes to a directory path, then the widespread convention among most worldwide organizations and most open source projects is to render If you look at other organizations and tools, such as many popular webservers (e.g. NGINX, Apache, Caddy, etc.) and many popular blog tools (e.g. Jekyll, Hugo, Zola, etc.) then you'll see that the tools have special handling that favors file names If you would like, I'm happy to take your request to Microsoft people to see ifhow they may be able to look at this, with the outcome being rendering more kinds of files from markdown to HTML here on GitHub. Any ideas or thoughts about this? |
Yeah, I guess I should have specified that It could even be specified in a config file, e.g. That being said, since this repo is on GitHub, I still think it's worth following their convention for now. If/when they install the enhancement, it is really easy to change back using the script I included above. |
Your way is better with
Well, the repo is involved in a lot of places, including webservers, bookmarks, and blog pipelines that use The previous two times I've seen this happen, MIcrosoft did the right thing, and fixed the naming areas. So I'm hopeful Microsoft will listen to your idea and take it seriously. In the meantime, to get you want you want ASAP, could it work OK for you if your script copies index.md to readme.md? This means two files, which isn't totally ideal, yet does get you a pragmatic solution for now. What do you think? |
Ah, I didn't realize the repo is used in other applications that require the filename to be I think that's another good use case for allowing the user to choose their rendering preference. In my opinion, having duplicate files is a bit overkill, so I can close this PR. I have my fork that I can use in the meantime. |
OK good. If you've heard of "Chesterton's Fence", that's the kind of idea of the repo links that you correctly mention. (Or if you're new to the fence, it's a nifty shorthand) |
Renamed all of the markdown files in
/doc
fromindex.md
toreadme.md
so that they are easily browsable on GitHub.