💾 Archived View for jb55.com › ward.asia.wiki.org › correct-markdown captured on 2022-01-08 at 13:51:05. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-04)
-=-=-=-=-=-=-
Markdown collects a handful of internet news group conventions as a counterpoint to the at one time simple but still unattractive html markup. Wiki markdown borrows some of these in order to render styles appropriate to its narrow anti-paper pages. This much it should do well.
Github's free pages has made their flavor of markdown popular among documentation authors. Github actually offers two flavors of markdown depending on whether the rendering is tightly connected to their database backend or not. We use their checklists to show off our persistence.
See Mixed Content where we motivate our use of plugins.
We intentionally limit our flavor of markdown in order to discourage elaborate page layout. Complex presentation interferes with sharing and subsequent refactoring.
We limit heading size to one size.
We limit bullet depth to one deep.
We limit paragraphs to one paragraph.
We encode links with wiki notation and semantics.
We defer images to the image plugin.
We defer tables to the html plugin.
Our implementation translates markdown to html one line at a time. This hinders translation to html markup that encloses other markup.
We don't wrap bullet lists with necessary markup to have them rendered properly in all browsers.
We don't attempt to recognize block quotes.
We squash blank lines which would normally separate markdown paragraphs but don't support the split/join interpretation of enter/delete keystrokes that would provide a substitute.
Numerous markdown to html translators exist in the open source. Some of these are modular or pluggable recognizing the desire of implementers to flavor the translation.
Paul has configured one translator to handle wiki conventions for links and maybe other notations. This increment on a featureful implementation is more likely to satisfy a markdown-only author than the from a blank slate implementation we currently have.
The react base wiki reader used showdown to provide the rendering for the markdown plugin. It used an extention to handle wiki links, but this should not be needed in the current client as we already have code to handle links.
Paul has also suggested round-trip translation from and to the notation of the editor's preference. An html subset or equivalent would be the interchange format. This could be tested in isolation but this alone would defeat the universal intention of the suggestion.
The current wiki editor will not break markdown text into multiple markdown items. It would be good to create a new markdown item when `enter` is pressed twice. This would mimic the behaviour seen with paragraph items, and not require either using the factory for the creation of each new item or writing as paragraph items and shift+clicking to convert to markdown.
Paul has prepared a new implementation consistent with these notes and now under review. github
Consistent list indentation. mozilla
We can exercise any replacement plugin by using search to find pages using the existing plugin, dragging them to the test environment, and then judging the quality of formatting provided in each case.
This search finds 3543 titles on 5986 pages. Given that today's federation has 33448 visible pages that makes for just under 18% that require markdown to render. data
Administrators, use this Plugmatic to install the improved plugin on your server. Drag this page to a site you own and host. Green says you have it already. Click yellow or red to get the install choices. Pick the published version.
Here we illustrate two features of wiki flavored markdown which are difficult to reproduce outside of the wiki environment: collaborative links and task lists.
See Mixed Content which we find from context.
- [x] Checkbox state stored in journal.