GitHub does provide some in-browser editing features, which are an improvement. You are also subjecting potential visitors to your repository with in-process edits to your Markdown files. “tweak README.md” type messages, when you really are doing one big edit to README.md and one logical commit. At the same time, your commit history becomes filled with
You edit, commit, push, reload, repeat – until you’re satisfied with your results. The development cycle described so far is rather awkward and time consuming. For example, when you Markdown source contains: This is a title Markdown syntax is close to natural language, but you really don’t know what your text will look like on GitHub until you commit your Markdown file edits and look at it rendered in your browser. In creating the Markdown files, I basically just used my editor or IDE. I do know my own experience is that my README.md file for SilkJS started out with just a paragraph or two, and then I added to it over time. I don’t see people write much about how they create their README.md files or maintain their Wiki pages. One thing I notice about the vast majority of these and others I view there is that many have long involved README.md files but have no Wiki pages at all. Over the years I’ve starred a couple hundred repositories on GitHub. GFM does not support this, so you will see the actual characters in your page and not a table of contents – you probably don’t want that. For example, some flavors of Markdown support and will automatically generate a table of contents in its place when rendered. Note: the risk of using any editing tools that support extensions to Markdown beyond GFM is that you include these extensions in your Markdown.
However, I’m going to focus on tools that are ideally suited for GitHub Flavored Markdown (GFM). There are a number of Markdown variants, including some with very neat features like automatically generated tables of content. In this post, I will introduce a few tools that facilitate the creation and maintenance of Markdown source files that are intended to be shown on GitHub.