Skip to content

Latest commit

 

History

History
148 lines (109 loc) · 5.01 KB

README.md

File metadata and controls

148 lines (109 loc) · 5.01 KB
Raw

Markdown - Still fork

build

A simple Elixir Markdown to HTML conversion library.

Implemented entirely as a NIF binding to the Hoedown library.

This fork of devinius/markdown was created to keep a stable source for the markdown Elixir package supporting the full range of hoedown configurations options and the use of dirty schedulers. You should be able to reference any master commits on your mix.exs dependency declaration, as they will not disappear.

The base version of this fork is d065dbc.

Installation

Add markdown to your list of dependencies on mix.exs. Make sure you reference this repo:

def deps do
  # consider adding a ref for a specific commit
  [{:markdown, github: "subvisual/markdown"}]
end

Usage

iex> Markdown.to_html "# Hello World"
"<h1>Hello World</h1>\n"

iex> Markdown.to_html "http://elixir-lang.org/", autolink: true
"<p><a href=\"http://elixir-lang.org/\">http://elixir-lang.org/</a></p>\n"

Options

All of these default to false:

  • :autolink - Automatically turn URLs into links.
  • :disable_indented_code - Don't indented code blocks as <code>.
  • :escape - Escape all HTML tags.
  • :fenced_code - Enables fenced code blocks.
  • :hard_wrap - Replace line breaks with <hr> tags.
  • :highlight - Replace ==highlight== blocks with <mark> tags.
  • :math - Parse TeX-based $$math$$ syntax.
  • :math_explicit - Requires math: true. Parse $math$ as inline and $$math$$ as blocks, instead of attempting to guess.
  • :no_intra_emphasis - Don't parse underscores_between_words as <em> tags.
  • :quote - Render "quotation marks" as <q> tags.
  • :skip_html - Strip HTML tags.
  • :space_headers - Require a space after # in the headers.
  • :strikethrough - Parse ~~text~~ as <del> tags.
  • :superscript - Parse ^text as <sup> tags.
  • :tables - Enables Markdown Extra style tables.
  • :underline - Parse _text_ as <u> tags.
  • :use_xhtml - Use XHTML instead of HTML.

You can find examples in the test module.

Dirty Scheduling

By default the NIF is deemed as clean for input lower than 30k characters. For inputs over this value, it is likely the render time will take over 1ms and thus it should be scheduled on a dirty scheduler.

Since it is impossible to know beforehand, if an input will take over 1ms to be processed, the 30k threshold is considered an arbitrary value. See subvisual/markdown#1.

This value can be configured by setting the following in your config/config.exs:

config :markdown, dirty_scheduling_threshold: 50_000

Profiling

There is basic profiling available. It should only be used for library development purposes. To enable it, compile the project with the PROFILE flag set:

PROFILE=1 make

This will compile a version that clocks the time before and after rendering and provides information regarding the type of scheduling being made.

The project includes five fixture markdown files of various sizes and the bundled .iex.exs file defines a module to read from those. You can use them to check the profiling info by doing so:

# run:
# PROFILE=1 make && iex -S mix
# before trying these examples:

iex(1)> Fxt.small() |> Markdown.to_html()
[markdown.c]: Input below arbitrary threshold. Running regular NIF.
[markdown.c]: Input size: 3399
[markdown.c]: Parsing time: 0.091ms.
"<hr>\n\n<p>path: /posts/69-undersampling-of-failure/\n" <> ...

iex(2)> Fxt.xlong() |> Markdown.to_html()
[markdown.c]: Input above arbitrary threshold. Running dirty NIF.
[markdown.c]: Input size: 55506
[markdown.c]: Parsing time: 2.087ms.
"<h1>Markdown: Syntax</h1>\n\n<ul id=\"ProjectSubmenu\">\n" <> ...

Contributing

Feel free to contribute.

If you found a bug, open an issue. You can also open a PR for bugs or new features. Your PRs will be reviewed and subject to our style guide and linters.

All contributions must follow the Code of Conduct and Subvisual's guides.

TODOs

A list of tasks anyone is free to tackle:

  • ANSI renderer

About

markdown was created by Devin Torres (@devinus) and this fork is maintained with ❤️ by Subvisual.

Subvisual