Page MenuHomePhabricator

Reserve ``` ``` syntax to indicate 'code' blocks in wikitext markup..
Open, LowPublicFeature

Description

Feature summary (what you would like to be able to do):

Discord and remarkup (on Phabriactor) use

``` ```
to indicate that a portion of input text is 'source-code' which should be displayed in an appropriate monospace font , with whitespace in the source not being ignored ( <PRE></PRE>`) behaviour, and on which (If supported) appropriate syntax highlighting should be added.

It is proposed that the
``` ```
syntax be reserved for this purpose in the markup Mediawiki uses, to assist in the transfer of code examples or samples between the content of Mediawiki pages, Discord discussions, and bug reports here on Phabricator.

Usage example:-

<code><nowiki> for each( function) do{ miracles}</nowiki><code>

would become :
```
for each (function do {miracles}
```

This feature is requested as a result of a discussion here:-

https://discord.com/channels/221049808784326656/291940905240231937/864218445109002280

Event Timeline

ShakespeareFan00 updated the task description. (Show Details)
ShakespeareFan00 updated the task description. (Show Details)

Copying some discussion from slack.

This feature has definitely been considered and requested before; I'd be surprised if there wasn't already a phab task or two buried in prehistory.

Somewhat related (and something which subbu prototyped at one point) was the ability to write certain pages in markdown, as opposed to wikitext, specifically to allow some of this content which is easier to write with markdown markup.

One criticism raised in the past against adding special markup for <code> is that "wikitext is for encyclopedias" and <code> sections, although interesting to us developers and used on wikitech and to document our own work, isn't used nearly as much on the projects. So the amount of work required to reserve the backtick characters "just for something developers want and not normal people" may be unwarranted. (Not necessarily making this argument myself, just relaying what I've been told in the past. So don't shoot the messenger!)

There are basically three paths forward on this:

  1. Add markdown as a first-class content type on wikis, or at least on certain wikis that opt-in. This would accept the market dominance of markdown, especially for code-related uses, and reduce friction when transferring content to/from a README.md to a wikipage. Folks authoring a lot of content using <code> blocks would probably choose to author that content in markdown, instead of wikitext. A couple of different implementation options; the most appealing is to use Parsoid MediaWiki DOM as an intermediate representation in order to decouple the editor and the content storage. You could use a "markdown editor" on wikitext Content, or a "wikitext editor" on markdown Content, using the appropriate converters. OTOH this is much harder than just defining a markdown Content type and a specialized editor widget and not worrying about interoperability. The main challenge here is that markdown does not have any obvious extension mechanisms built in, so it is hard to figure out exactly what a "mediawiki-flavored markdown" would look like: how would you represent templates or distinguish wikilinks, etc. T112999: Let MediaWiki operate entirely without wikitext discusses how to better support alternative content types on wiki.
  2. Backtick-for-code is on my shortlist for "wikitext 2.0". The idea of wikitext 2.0 is that it is regularized version of wikitext that looks as much like wikitext 1.0 as possible but shaves off the corner cases. One strawman is T149659: Grunge, or "zoom". The idea would be to (again) use the MediaWiki DOM as an intermediate representation, so that articles could be stored in "wikitext 1" or "wikitext 2" more-or-less transparently, and you could more-or-less transparently choose whether to edit the page in a "wikitext 1" or "wikitext 2" or "visual" editor. So you might just switch over to "wikitext 2" mode, write all your backtick escaped stuff, then save as wikitext 1 and have all that content surrounded with <source> and <code> tags "magically".
  3. Actually support this markup in "wikitext 1". The very first step here is to lint and remove/replace all conflicting uses of backtick on the wiki. So you're write a linter tool or bot to look through all our existing content and nowiki (or something) all the backticks. When we'd done this work and been reasonably convinced that the amount of remaining pages that would be broken by adding backtick as a metacharacter are "few enough", then the actual parser work to implement backtick escapes would be relatively straightforward.