What markdown options are available? - Meta

TopAnswers Meta

Top Answer

Jack Douglas

We are using [markdown-it](https://github.com/markdown-it/markdown-it), which:

* Has a useful [demo] page that you linked to in the question.

* Follows the [CommonMark] spec, except that on TopAnswers we ***[don't allow HTML input at all][safe]***, so no `<br>`, `sup` etc [that you can use on SE][sehtml][^pluginforhtml][^plugin].

* Isn't otherwise a radical departure from Markdown on SE, but there are a few more gotcha's such as:

    1. Strikethrough in SE chat is `---strikethrough---` but CommonMark does not support strikethrough (however see below for our plugin support for `~~strikethrough~~`).

    1. Markdown-it doesn't collapse adjacent blockquotes into a single blockquote:
    
        ```
        > this is two

        > blockquotes

        > this is a single
        >
        > blockquote with two paragraphs
        ```

    1. Various other minor details from [this official CommonMark list][cmdiffs].
    
* Has some very sensible optional extensions (plugins) built-in — these are not part of the CommonMark spec but we have them switched on globally:
    1. GitHub-style [strikethrough]
    1. GitHub-style [tables]
    
* Has extensive support for other extensions, and we can add more or even create our own[^plugin].

    * The following 'official'[^moreplugins] extensions are currently supported globally on TopAnswers:
        1. [linkify]
        1. [syntax highlighting][highlight][^syntax]
        1. [superscript][][^supersub]
        1. [subscript][][^supersub]
        1. [abbreviations][abbr]
        1. [definition lists][deflist]
        1. [footnotes]
        1. [emoji]
        
    * The following custom extensions are also currently supported globally:

        * tweaking 'fuzzy' `dba.se` links to point to `dba.stackexchange.com`
        * line numbers are available for fenced code blocks[^syntax] : ` ``` #`, or with a language, ` ``` apl #`, or to begin at a specified line number, ` ``` apl #3`
        
    * Not actually a markdown plugin presently, but may be implemented as a plugin in future, and behaves similar to a plugin now:
        * integration with [db<>fiddle], using this block level syntax:
            ```
            <>https://dbfiddle.uk/?rdbms=postgres_11&fiddle=71940aadda50f55bfede87606cd1dc2c`
            ```
    
[^pluginforhtml]: If you miss something that you can only do in with inline HTML on SE, it may be available as a plugin for markdown-it, or we can write our own.
[^plugin]: We'll need to be careful about adding non-standard syntax, but all requests for plugin support will be carefully considered — please ask here on meta for global support or with a meta question on the community site if it is site-specific like [MathML] or [Mathjax].
[^moreplugins]: There are a lot of other plugins, probably of widely varying quality and sanity, [listed on npm][npm]
[^syntax]: To chose a language for a code block, you need to use a [fenced code block](https://spec.commonmark.org/0.27/#fenced-code-blocks) and specify the language after the fence (e.g. `~~~none`, or the same with backticks ` ```none`)
[^supersub]: Note that spaces currently [need to be escaped](https://github.com/markdown-it/markdown-it-sup/issues/3) if you want to super/subscript multiple words (demo [here](https://markdown-it.github.io/#md3=%7B%22source%22%3A%22-%20not%20%5Eup%2C%20up%2C%20and%20away%5E%20%28%3D%20superscript%20ignored%29%5Cn-%20%26nbsp%3B%5Cn-%20but%20%5Eup%2C%5C%5C%20up%2C%5C%5C%20and%5C%5C%20away%5E%20%5Cn%5Cnor%20%5Cn%5Cn-%20not%20~swing%20low~%20%28%3D%20subscript%20ignored%29%5Cn-%20but%20~swing%5C%5C%20low~%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D)).

[demo]: https://markdown-it.github.io
[CommonMark]: https://commonmark.org
[safe]: https://talk.commonmark.org/t/make-commonmark-safe-by-default/1265
[sehtml]: https://meta.stackexchange.com/a/135909
[cmdiffs]: https://github.com/commonmark/commonmark-spec#user-content-differences-from-original-markdown
[MathML]: https://github.com/runarberg/markdown-it-math
[Mathjax]: https://github.com/classeur/markdown-it-mathjax
[strikethrough]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text
[tables]: https://help.github.com/articles/organizing-information-with-tables
[linkify]: https://github.com/markdown-it/markdown-it#linkify
[highlight]: https://github.com/markdown-it/markdown-it#syntax-highlighting
[superscript]: https://github.com/markdown-it/markdown-it-sup
[subscript]: https://github.com/markdown-it/markdown-it-sub
[abbr]: https://github.com/markdown-it/markdown-it-abbr
[deflist]: https://github.com/markdown-it/markdown-it-deflist
[footnotes]: https://github.com/markdown-it/markdown-it-footnote 
[emoji]: https://github.com/markdown-it/markdown-it-emoji
[db<>fiddle]: https://dbfiddle.uk
[npm]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin

::: quote 4 52158 96209a8c04569e7f6099be32bb73ba169e64e1579287f540ec2421c66ba6d9e3 212,223,236 62,103,153 Paul White *— 19 hours ago* *in [stop the merry-go-round](/databases?room=4#c52158)* >Anyway >I think I've come to the conclusion that this is a good way to write The Query(TM): > >```sql >/* >CREATE INDEX i ON dbo.Votes (VoteTypeId) >INCLUDE (UserId, CreationDate, BountyAmount, PostId); >*/ > >DECLARE @VoteTypeId integer = 1; > >SELECT > ISNULL(V.UserId, 0) AS UserId, > V.Votes2013, > V.TotalBounty, > V.PostCount, > V.VoteTypeId >FROM >( > SELECT > v.UserId, > SUM(CASE WHEN v.CreationDate >= '20130101' > AND v.CreationDate < '20140101' > THEN 1 > ELSE 0 > END) AS Votes2013, > SUM(CASE WHEN v.BountyAmount IS NULL > THEN 0 > ELSE 1 > END) AS TotalBounty, > COUNT(DISTINCT v.PostId) AS PostCount, > @VoteTypeId AS VoteTypeId > FROM dbo.Votes AS V > WITH (INDEX (i)) > WHERE > V.VoteTypeId = @VoteTypeId > GROUP BY > V.UserId >) AS V >WHERE NOT EXISTS >( > SELECT 1/0 > FROM dbo.Posts AS p > JOIN dbo.Badges AS b > ON b.UserId = p.OwnerUserId > WHERE p.OwnerUserId = V.UserId > AND p.PostTypeId = 1 >) >OPTION (RECOMPILE); >``` :::

@Jack Is it possible the recent changes somehow made it impossible to select all the text in a code block? That's what I'm seeing in Edge browser anyway. A code block with a scroll bar in chat doesn't scroll when dragging a text selection down.

(If the backticks "fill" the quotation marks, it's all good, so #3 in [updated dingus][d]. ) [d]: https://markdown-it.github.io/#md3=%7B%22source%22%3A%22%5C%5C%5B1%5C%5C%5D%20%5C%22last%20%60%3Cli%3E%60%5C%22%20or%20%5C%22%60ul%60%20list%5C%22%20or%20%5Cn%5Cn%5C%5C%5B2%5C%5C%5D%20but%20%5C%22last%20%3Cli%3E%5C%22%2C%20or%20%5C%22last%20%60%3Cli%3E%60%20tag%5C%22%5Cn%5Cn%5C%5C%5B3%5C%5C%5D%20and%20%5C%22%60backtick%60%5C%22%20is%20good!%5Cn%5CnExamples%20in%20line%20%5C%5C%5B1%5C%5C%5D%20do%20not%20get%20curly-quotes.%5Cn%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D

I tried this in the Markdown-it dingus, and it [comes out a bit different][1]. [1]: https://markdown-it.github.io/#md3=%7B%22source%22%3A%22%5C%5C%5B1%5C%5C%5D%20%5C%22last%20%60%3Cli%3E%60%5C%22%20or%20%5C%22%60ul%60%20list%5C%22%5Cn%5Cn%5C%5C%5B2%5C%5C%5D%20but%20%5C%22last%20%3Cli%3E%5C%22%2C%20or%20%5C%22last%20%60%3Cli%3E%60%20tag%5C%22%5Cn%5CnExamples%20in%20line%20%5C%5C%5B1%5C%5C%5D%20do%20not%20get%20curly-quotes.%5Cn%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D

Good morning, @Jack ! Today's Funny Thing. Have a look at the first set of quotation marks in [this question](https://topanswers.xyz/web?q=1053). For me, it looks like this: ![__0-0a-a-ta-quotes.png](/image?hash=7a7579004d0863806c5b739b2e86865788d0c1e4156d536800dfec184a5d35e5)

I think they just collapse to zero width on their own — not sure whether that matters because I guess you wouldn't usually post them like that? We could put a minimum-width on them if you think that would help?

@Jack Would it be worth adding the (really quite cool!) [syntax for code-block line-numbering](https://topanswers.xyz/transcript?room=1103&id=50468#c50468) to footnote 4 ... or somewhere here? It's not a feature that I'm familiar with, and possibly quite a few others.

yes that's server-side — we made an early choice to render client-side so needed a js library. Incidentally, `[a wee CMS](picocms.org)` doesn't work here or on SE — though interestingly they fail in different ways (SE's way is superior from a user's POV but not CommonMark compliant). You do need the protocol…

Thanks, Jack - interesting thread! I've just been looking at [a wee CMS](picocms.org/) that currently uses Parsedown (and its "Extra"), but is contemplating replacing that. I didn't know whether Markdown-It would be a sensible option; possibly different technologies involved? Anyway, thanks again for the reply.

::: quote 661 17222 ba1d6fd8881a87067fe28d71a5ddc594f0146228d32fe77a6399565d3b928bd8 219,219,219 131,133,133 Jack Douglas replying to Adám *— 3 months ago* *in [Make tables use proportional font](/meta?q=646#c17222)* >allowing even limited html means risk: https://talk.commonmark.org/t/make-commonmark-safe-by-default/1265 :::

@Jack Did you ever document anywhere how you came to the decision to use Markdown-it rather than one of the other options available to you? That would be interesting to know ... well, for people who find that kind of thing interesting! :grimacing: (Like me....)

1 Answer