Which Markdown and How To View It?

[orcmid]

In using Git and especially GitHub as a vehicle for collaborative authoring -- at least authoring in the open -- the temptation is to treat Markdown as the "source" and various transformations from it as targets. It's more complicated than that. In GitHub there are two ways to view a repository Markdown (*.md) file: raw, as actually written, and pretty as an HTML rendering of the raw file.

The GitHub pretty view is based on what is termed GitHub Markdown. There is a slight problem with that. Not all markdowns in GitHub are rendered the same. This comment is an example of one flavor. there are potentially different flavors (different than in repository and README.md views) for Markdown in a Github-Pages-processed folder (such as docs here), in an associated Wiki, in Inssues and Discussions, and maybe on Gist pages.

I also have a concern about the stability of GitHub Mardown. There does not seem to be a good way to annotate such assumptions in an actual .md file. Using HTML comments works, but it is a concession to rendering in HTML. I don't know what YAML top-marking might also be handled passively in the GitHub pretty view. I will test that.

The next concern about reliance on Markdown as the authored form has to do with the reliability of GitHub pretty for proof-reading by authors, without having to conduct a full rendering to a publication draft for proof-reading and copy-editing.. It is important to avoid conflicts with features of one that have undesirable consequences in the other.

There are also lifecycle issues in the handling of edits and proofing by others and how changes are recommended, accepted, and reflected. The provisions of Git and the way that changes are presented and individually accepted/rejected/adjusted by editors comes into the picture.

While this can be taken as over-thinking the problem, it will matter in coming up with an approach that has some enduring value.

[orcmid]

The following came up in examination of a pull request involving Markdown files intended for Peruse rendering.

[Meta-consideration] ...

I think the paragraph in this change doesn't have internal line breaks so the whole paragraph is formally one line. That's the reason we see it completely marked as change in GitHub comparison. Inside a paragraph,...

Yes, on reflection, the meta-consideration isi about Peruse and also about Amy Ko's chosen form for entering paragraphs. One should not do anything about original authored paragraphs in single lines, something our text editors might reflow but are tough to examine in "raw." The unintended consequence has to do with how (GitHub) DIFF comparisons are tied to the raw-text line level.

I notice that the raw files we are looking at do have blank lines between paragraphs, and those matter for the GitHub rendering of these Markdown pages. What I can't tell here is whether or not that matters for Peruse, although the Peruse tutorial document also has such blank lines. Breaking up a paragraph into multiple raw-text lines as part of making changes in a pull-request makes incidental changes that are probably objectionable, not achieving any useful DIFF improvement at all. A quandary.

For some of these questions, I think it is necessary to install Peruse and see how it renders the tutorial document in HTML. Looking at Peruse-intended Markdown files via GitHub Markdown rendering does not answer these and other questions.

[2021-04-30T15:15Z One of the first idioms learned when I started programming was for exchanging the values of two variables involving a third intermediate one was just applied here to reording of the main comment and a follow-on.]

[orcmid]

Yet Another Markdown Consideration

There is an additional case where Markdown files may be previewed and the Markdown flavor might be different. Off-line editors.

For example, Microsoft Visual Studio Code recognizes Markdown (.md) files and provides filtering. It also provides preview capability. That's pretty handy for editing Issue and Discussion entries off-line, pasting them in when they are satisfactory. It avoids the problem of in-browser editing and loss because of browser closing or other mishap.

[orcmid]

docs.microsoft.com as another case

The production of Microsoft Docs on-line involves a lifecycle and publication document engineering also housed on Github. An useful breakdown of the repositories and the to-the-web (and PDF) publishing are found in the contribution approacch and its publication.

It is apparent that there is yet-another yet-another markdown. This is part of Microsoft's Open Publishing Services and the details of the Markdown and extensions is documented in the system along with information on tools and their use in this context.

Although one might not want to employ the model directly, there is much to admire, especially in the attention to on-ramping and also providing different levels of participation that are more accommodating for end-user contributions. I find much inspiration in this effort.