Ruby Markdown

Posted on  by admin

Markdown is a wonderfully simple approach to creating web pages, written by John Gruber of Daring Fireball. You get on with the business of writing (without any fancy code) and Markdown takes care of producing clean, web standards compliant HTML. In response to this question, Is there any difference between 旅行者 and 旅人?, the answerer used ruby for the two pertinent words. I was delightfully surprised to find it's accomplished with simple, self. Kramdown is a fast, pure Ruby Markdown superset converter, using a strict syntax definition and supporting several common extensions. Word-to-markdown 1 1,220 1.4 Ruby. Stack Overflow Public questions & answers; Stack Overflow for Teams Where developers & technologists share private knowledge with coworkers; Jobs Programming & related technical career opportunities.

  1. Ruby Markdown Library
28 August 2018

by Alex Harvey

I recently spent some time automating the generation of Markdown tables-of-contents for compatibility with my open source projects in Github and also Gitlab Cloud. In the process, I reviewed a number of auto table-of-contents options by Markdown flavour and version, which I will document here.

Github Markdown

Github uses Github Flavoured Markdown (GFM), which is based on the CommonMark spec. GFM is documented here. As such, a table of contents is something you are expected to write yourself in Markdown, using inline links.

For example:

There are tools out there to auto-generate tables of contents e.g. markdown-toc, but I wanted something simpler and I wrote my own Ruby script to do it. My script is gen_markdown_toc.rb.

To use it (on a Mac):

Then copy the generated text in your Markdown file where you want the table of contents to appear.

Gitlab Markdown

As of now, Gitlab Cloud Markdown uses GFM as well, or at least the version of Gitlab Cloud that I tested this on does.

Note that Gitlab’s docs here reveal that until recently Gitlab used Kramdown under the hood (see below). I discovered this page here that explains why they migrated away from Kramdown and thereby broke the useful table of contents feature.

Bitbucket Markdown

According to documentation here, Bitbucket’s Markdown is also based on CommonMark, so I would expect my script to work on Bitbucket too.

Kramdown Markdown

Meanwhile, other versions of Markdown have built in features to auto-generate tables of contents. Kramdown documented here is a Ruby implementation of Markdown that makes tables of contents a lot easier. If you are using Kramdown, you just need to add this:

This Jekyll blog uses Kramdown Markdown for example.

RedCarpet Markdown

RedCarpet documented here is another flavour that makes auto-generation of tables of contents easy. It is apparently used in Gitlab’s Wikis. Just add this for a table of contents:

Typora Markdown

Another flavour is Typora Markdown documented here. For a ToC you can write:

End note

These are all the Markdown formats I am aware of. I would like to keep this page up to date and to that end I welcome feedback and updates.

tags: markdown

RDoc::Markdown as described by the markdownsyntax.

To choose Markdown as your only default formatsee Saved Options atRDoc::Options for instructions on setting up a.doc_options file to store your project default.

Usage

Here is a brief example of using this parse to read a markdown file byhand.

Extensions

The following markdown extensions are supported by the parser, but not allare used in RDoc output by default.

RDoc

The RDocMarkdownparser has the following built-in behaviors that cannot be disabled.

Underscores embedded in words are never interpreted as emphasis. (While themarkdowndingus emphasizes in-word underscores, neither the Markdown syntax nor MarkdownTest mention thisbehavior.)

For HTML output, RDoc always auto-links bareURLs.

Break on Newline

The #break_on_newlineextension converts all newlines into hard line breaks as in Github FlavoredMarkdown. This extension is disabled by default.

CSS

The css extension enables CSSblocks to be included in the output, but they are not used for any built-inRDoc output format. This extension is disabledby default.

Example:

Definition Lists

The #definition_listsextension allows definition lists using the PHPMarkdown Extra syntax, but only one label and definition are supportedat this time. This extension is enabled by default.

Example:

Produces:

cat

A small furry mammal that seems to sleep a lot

ant

A little insect that is known to enjoy picnics

Github

The github extension enables apartial set of Github FlavoredMarkdown. This extension is enabled by default.

Supported github extensions include:

Fenced code blocks

Use ``` around a block of code instead of indenting it fourspaces.

Syntax highlighting

Use ``` ruby as the start of a code fence to add syntaxhighlighting. (Currently only ruby syntax is supported).

HTML

Enables raw HTML to be included in the output. This extension is enabled bydefault.

Ruby markdown website

Example:

Notes

The notes extension enablesfootnote support. This extension is enabled by default.

Example:

Produces:

Here is some text1including an inline footnote 2

Limitations

  • Link titles are not used

  • Footnotes are collapsed into a single paragraph

Author

This markdown parser is a port to kpeg from peg-markdown by JohnMacFarlane.

It is used under the MIT license:

Permission is hereby granted, free of charge, to any person obtaining acopy of this software and associated documentation files (the “Software”),to deal in the Software without restriction, including without limitationthe rights to use, copy, modify, merge, publish, distribute, sublicense,and/or sell copies of the Software, and to permit persons to whom theSoftware is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included inall copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISINGFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHERDEALINGS IN THE SOFTWARE.

The port to kpeg was performed by Eric Hodel and Evan Phoenix

1 With the footnotetext down at the bottom

Ruby Markdown Library

2 for short footnotes