Dillinger is one of the best online Markdown editors. Just open the site and start typing in the left pane. A preview of the rendered document appears in the right pane. You’ll probably want to keep the Dillinger website open as you read through this guide. That way you can try the syntax as you learn about it.
- Overview
- Getting Started
- Supporting Eleventy
- Working with Templates
- Layouts
- Pagination
- Using Data
- Data Cascade
- Front Matter Data
- Global Data Files
- Data Cascade
- Configuration
- Filters
- Template Languages
- JavaScript
- Plugins
- News
- The Markdown Guide is a free and open-source reference guide that explains how to use Markdown, the simple and easy-to-use markup language you can use to format virtually any document. Get Started DigitalOcean App Platform, a new PaaS that gets your apps to market, faster.
- The Markdown Guide is a free and open-source reference guide that explains how to use Markdown, the simple and easy-to-use markup language you can use to format virtually any document. Get Started DigitalOcean App Platform, a new PaaS that gets your apps to market, faster.
Template Languages:
| Eleventy Short Name | File Extension | NPM Package |
|---|---|---|
md | .md | markdown-it |
Markdown Options #
Default Options #
html: true(markdown-itdefault isfalse)
The only listed options here are the ones that differ from the default markdown-it options. See all markdown-it options and defaults.
Optional: Set your own library instance New in v0.3.0#
Markdown Site Examples
Pass in your own instance of the Markdown library using the Configuration API. See all markdown-it options.
Add your own plugins New in v0.3.0#
Pass in your own markdown-it plugins using the setLibrary Configuration API method (building on the method described in “Using your own options”).
- Find your own
markdown-itplugin on NPM npm installthe plugin.
There are extra <pre> and <code> in my output #
Markdown has a lesser known feature called Indented Code Blocks, which means any content that is indented by four or more spaces (and has a preceding line break) will be transformed into a code block.
is transformed into:
(Example borrowed from the CommonMark Specification)
That means any content that follows this four (or more) space indent may be subject to transformation. If you pre-process your markdown using Nunjucks or Liquid or another templating engine, that means the content retrieved from an include or a shortcode may also fit this formatting. Careful when you include extra whitespace in your includes or shortcodes!
If you still wish to indent your template literals, you can use outdent to strip each line of indentation before handing it off to the renderer.
If your content indentation is still irregular and you do need to disable indented code blocks, you can do so by configuring your markdown-it instance to disable the code rule (following the 'Set your own library instance' procedure above).
Why can’t I return markdown from paired shortcodes to use in a markdown file? #
The truth is, you can return markdown inside shortcodes (as long as the file is transforming markdown, either as a .md file extension or with templateEngineOverride). However, there is one small wrinkle that might catch you off guard.
- Method A returns:
My really *important* content.which is successfully transformed as markdown intoMy really <em>important</em> content. - Method B returns:
<div>My really *important* content.</div>which markdown treats as an HTML block which cannot have nested markdown inside of it. It’s transformed into<div>My really *important* content.</div>. Read more at the CommonMark specification on HTML blocks.
Other pages in Template Languages:
- JavaScript
Related Docs
I've found a pattern I like using a python markdown generator to get a simple site up and running quickly. I had three main requirements
- Markdown
- I wanted to use Markdown as I use it day to day, and I think its a quick way to get ideas down without having to mess around with rich text formatting.
- Static Site
- I wanted to keep this as simple and clean as possible, just HTML, CSS and JS.
- Azure
- I wanted to deploy the site through Azure as its the cloud service I'm most familiar with.
MkDocs
MkDocs is a really elegant, fast way to build a static site from markdown. You can create a site from just a configuration file and a set of markdown files. Getting started is as simple as
And viola! You've got a site with navigation, search facility, table of contents and a theme that renders nicely on mobile and desktop.
Whenever you save a change to the site it gets rebuilt.
Adding new pages and updating the navigation is just updating the root mkdocs.yml YAML file to point towards new markdown files.
Themes
MkDocs comes with a selection of themes that can be easily installed through pip. In the end I went with Cinder, a clean style based on Bootstrap.After pip install mkdocs-cinder getting it going was updating the mkdocs.yml file.
Hosting Static Site
The quickest and easiest way for me to start hosting my site was through an Azure Storage account.Azure Storage supports Static Site Hosting where you can serve up the contents of a container called $web.
Building Site
Building the site is done through the mkdocs build command. This generates a sites directory. MkDocs will give you everything you need for your site, you just need to get those files served up over a web server.
I just used Azure Storage Explorer to upload the generated site directory into Azure Storage.
In future I'm going to look at how to automate this step so the site can be rebuilt and re-uploaded every time a new version is created (Azure Functions with an Event on the Storage Container possibly). Lexmark x3550 driver windows 10.
Adding a CDN
Something that caused me a lot of frustration and wasted time was trying to link my domain name to my storage. Ideally I wanted to serve up the contents of my storage straight through the dishy.dev domain name. I couldn't get the storage serving up over the root domain, it was always on a subdomain.
Markdown Site
In the end I found out that the scenario I was trying to do wasn't possible, and that using a CDN to serve up the storage contents would allow me to quickly link my domain.
Sitecore Markdown
CDN setup can be quite confusing but Microsoft have some good guidance on how to do it. Remember to enable http to https redirection in your CDN rules. And if you want to let people access your site without needing 'www.' at the front Arlan Blogs - Adding a Root Domain to Azure CDN Endpoint has instructions on how to do this.
Adding Telemetry
In the mkdocs.yml I added a link to an Azure Application Insights Snippet to let me see what sort of traffic the site was generating.
Markdown Site Login
And there you have it, not bad for a couple of hours work. A really quick way to stand up a quick site for blogging or documentation.
Markdown Site Template
MkDocs is very extendable with a lot of plugins available to easily expand your site. Tagging of your pages, Minifiers for your build etc so there's plenty of scope to build more complex sites.