I use Pandoc to create content for my website.
For example, I have the following content on a page:
# About me
Some text.
## My hobbies
### Hiking
Some text about hiking.
### Dancing
Some text about dancing.
### Other
Some text about other.
## Why I love Pandoc
Some more text.
Pandoc parses this for me and outputs nice HTML.
But I want to post-process this HTML further, for example I want the hobbies part to become an accordion.
For this I'd like it to be in its own container, e.g. a <div class="accordion">. Is this possible somehow?
Update
By attaching a class to the specific heading, I can achieve something close to what I need:
## My hobbies {.accordion}
...
Now I can target everything using CSS like this (code not tested):
h2.accordion ~ *:not(h1, h2) {
color: red;
}
This assumes that the everything up to the next heading on the same (or higher) level belongs to the carousel.
This can be of help. I don't know though whether it fits all my requirements, but it's a start.
Sure, markdown supports raw HTML and native divs:
## My hobbies
<div class="hobbies">
### Hiking
Some text about hiking.
</div>
And since pandoc 2.0 even fenced_divs:
## My hobbies
::: hobbies
### Hiking
Some text about hiking.
:::
Related
Is there a markdown flavor / extension that allows to structure a document using nested blocks instead of using headings levels ?
My problem with the latter approach is that if you separate your markdown files (and then use pandoc or anything else to combine them) you have to keep track of your headings levels across multiple files. And if one day you decide to change a sub-sub-section into a sub-section you need to change all the headings inside this section.
For now, I have a plugin that allows me to parse a markdown file like this (changing the rules for code blocks and headings) :
# Title
A paragraph
# Sub-title
A paragraph in a sub-section
Into this :
<section>
<h1>Title</h1>
<p>A paragrpah</p>
<section>
<h2>Sub-title</h2>
<p>A paragraph in a sub-section</p>
</section>
</section>
Is there a problem with this indentation-based approach ? I suppose I am not the first one to try to use a nested structure, but I can't find useful resources online.
My markdown was created according to the style from this top-result cheatsheet with HTML directives, using this commmand:
pandoc -f gfm -t html --atx-headers -s -o out.html in.md
However, the generated html always ignores titles that contains the following HTML code above them, leaving tons of ###, #### in my output HTML. My titles look like these:
# H1
<a name=toc-anchor-h2 />
## H2
<a name=toc-anchor-h3 />
### H3
<a name=toc-anchor-h4 />
#### H4
Then H1 works fine, but the # in the rest levels are all seen by pandoc as plain text. How should I solve this problem?
The headers must be preceded by a blank line. The missing blank line is causing the Markdown parser to not recognize them as headers. Therefore, edit your document to the following:
# H1
<a name=toc-anchor-h2 />
## H2
<a name=toc-anchor-h3 />
### H3
<a name=toc-anchor-h4 />
#### H4
Of, if you are concerned that that moves the anchors too far away from the intended target, include them inline:
# H1
## <a name=toc-anchor-h2 />H2
### <a name=toc-anchor-h3 />H3
#### <a name=toc-anchor-h4 />H4
Or, as you are using Pandoc, you could use one of the many Pandocs extensions which assigns identifiers directly to each header.
As it turns out, Pandoc's gfm variant of Markdown (which you are using) already includes the auto_identifiers extension. As the name implies, the auto_identifiers extension will cause id attributes to be auto-generated for every header. As a reminder, assigning an id attribute to an HTML element has the same effect as defining an anchor; you can link to either with a hash fragment. Therefore, you could simply remove your anchors and use the auto-generated ids which have already been assigned to the headers themselves.
However, if you would like to define your own custom id attributes for each header, then you may want to enable the header_attributes extension and alter your Markdown as follows:
# H1
## H2 {#toc-anchor-h2}
### H3 {#toc-anchor-h3}
#### H4 {#toc-anchor-h4}
which would generate the following HTML:
<h1 id="h1">H1</h1>
<h2 id="toc-anchor-h2">H2</h2>
<h3 id="toc-anchor-h3">H3</h3>
<h4 id="toc-anchor-h4">H4</h4>
Note that the "H1" header has an auto id assigned (based upon the text content of the element), while the remaining headers have the custom ids assigned to them.
One word of caution regarding the header_attributes extension: The syntax for defining the custom ids is non-standard and not supported by most Markdown implementations. If you want portable Markdown, then you should probably stick to the auto-generated ids as that does not require any non-standard markup in your documents.
Update: Note that according to the docs, the header_attributes extension is not compatible with gfm. Therefore, you wouldn't be able to use that extension. However, you get auto_identifiers by default. If you want custom identifiers, the you would need to use the custom raw HTML anchors. Of course that gives you the added benefit of a portable Markdown document.
I am using MarkEd which implements GitHub flavoured markdown.
I have some working markdown:
## Test heading
a paragraph.
## second heading
another paragraph
Which creates:
<h2 id="test-heading">Test heading</h2>
<p>a paragraph.</p>
<h2 id="second-heading">second heading</h2>
<p>another paragraph</p>
I would like to wrap that markdown section in a div, eg:
<div class="blog-post">
## Test heading
a paragraph.
## second heading
another paragraph
</div>
However this returns the following HTML:
<div class="blog-post">
## Test heading
a paragraph.
## second heading
another paragraph
</div>
Eg, no markdown, literally '## Test heading' appears in the HTML.
How can I properly wrap my markdown in a div?
I have found the following workaround, however it is ugly and not an actual fix:
<div class="blog-post">
<div></div>
## Test heading
a paragraph.
## second heading
another paragraph
</div>
Markdown
For Markdown, This is by design. From the Inline HTML section of the Markdown reference:
Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style emphasis inside an HTML block.
But it is explicitly allowed for span-level tags:
Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.
So, depending on your use-case, you might get away with using a span instead of a div.
CommonMark
If the library you use implements CommonMark, you are lucky. Example 108 and 109 of the spec show that if you keep an empty line in between the HTML block and the markdown code, the contents will be parsed as Markdown:
<div>
*Emphasized* text.
</div>
should work, while the following shouldn't:
<div>
*Emphasized* text.
</div>
And, again according to the same section in the reference, some implementations recognize an additional markdown=1 attribute on the HTML tag to enable parsing of Markdown inside it.
Though it doesn't seem to work in StackOverflow yet:
Testing **Markdown** inside a red-background div.
GitHub Pages supports the markdown="1" attribute to parse markdown inside HTML elements, e.g.
<div class="tip" markdown="1">Have **fun!**</div>
Note: As of 2019/03, this doesn't work on github.com, only GitHub Pages.
Note: Quotes, as in markdown="1", are not required by HTML5 but if you don't use quotes (markdown=1), GitHub does not recognize it as HTML. Also, support is buggy right now. You will likely get incorrect output if your HTML element is larger than a single paragraph. For example, due to bugs I was unable to embed a Markdown list inside a div.
If you find yourself in an environment in which markdown="1" doesn't work but span does, another option is to use <span style="display:block"> so that block-level classes are compatible with it, e.g.
<span style="display:block" class="note">It **works!**</span>
Tip: <span class="note"></span> is shorter than <div class="note" markdown="1"></div>, so if you control the CSS you might prefer to use <span> and add display: block; to your CSS.
Markdown Extra is needed to be able to for Markdown formatting works inside an HTML blocks, please check the documentation stated here -> https://michelf.ca/projects/php-markdown/extra/
Markdown Extra gives you a way to put Markdown-formatted text inside
any block-level tag. You do this by adding a markdown attribute to the
tag with the value 1 — which gives markdown="1"
Last resort option:
Some libraries may be case sensitive.
Try <DIV> instead of <div> and see what happens.
Markdownsharp has this characteristic - although on StackOverflow they strip out all DIVs anyway so don't expect it to work here.
By looking at the docs for Extending Marked and modifying the html renderer method, you can do something like this to replace the parts between tags with parsed markdown. I haven't done extensive testing, but it worked with my first few attempts.
const marked = require('marked');
const renderer = new marked.Renderer();
renderer.html = (mixedContent) => mixedContent.replace(/[^<>]+?(?=<)/g, (match) => {
const tokens = marked.lexer(match);
return marked.parser(tokens);
});
Edit
this new regex will ensure that only markdown with lines between it and the html tags will be parsed.
const marked = require('marked');
const renderer = new marked.Renderer();
renderer.html = (mixedContent) => mixedContent.replace(/\n\n[^<>]+?\n\n(?=<)/g, (match) => {
const tokens = marked.lexer(match);
return marked.parser(tokens);
});
In my case (on GitHub), the problem was resolved when I added newline between html tags and markdown text.
I'm using Kramdown's ToC generation in Jekyll and am wondering I can make it somehow support automatic numbering, so that this markdown:
## Header A
### Subheader
## Header B
Gets turned into this HTML:
<h2>1 Header A</h2>
<h3>1.1 Subheader</h3>
<h2>2 Header B</h2>
Apparently this could be done in CSS or JavaScript, but I'm looking for a Markdown->HTML only solution.
Pay attention to this part in kramdown documentation:
All attributes applied to the original list will also be applied to
the generated TOC list and it will get an ID of markdown-toc if no ID
was set.
So, simply replace
- This list will contain the toc (it doesn't matter what you write here)
{:toc}
with
1. This list will contain the toc (it doesn't matter what you write here)
{:toc}
to get numbered ToC instead of unnumbered.
As seen in kramdown config no way to get this natively.
The plugin way can solve this issue.
You can use https://github.com/A4Vision/enumerate-markdown
pip install enumerate-markdown
markdown-enum filename.md <minimal level> filenameoutput.md
Minimal level can be 1,2,3 etc depending on which header level you like to assign #1 to.
The github mentions no minimal level option as required, but in my case it only worked providing a level.
Example - input
# header 1
text
## header 2
text
# header 3
text
Output
# 1. header 1
text
## 1.1 header 2
text
# 2. header 3
text
As stated in Are numbered headings in Markdown / Rdiscount possible?
As headers are now numbered, they will be numbered in TOC and in your headers.
I'm trying to figure out how to reference another area of a page with Markdown. I can get it working if I add a
<div id="mylink" />
and for the link do:
[My link](#mylink)
But my guess is that there's some other way to do an in-page link in Markdown that doesn't involve the straight up div tag.
Any ideas?
See this answer.
In summary make a destination with
<a name="sometext"></a>
inserted anywhere in your markdown markup (for example in a header:
## heading<a name="headin"></a>
and link to it using the markdown linkage:
[This is the link text](#headin)
or
[some text](#sometext)
Don't use <div> -- this will mess up the layout for many renderers.
(I have changed id= to name= above. See this answer for the tedious explanation.)
I guess this depends on what you're using to generate html from your markdown. I noticed, that jekyll (it's used by gihub.io pages by default) automatically adds the id="" attribute to headings in the html it generates.
For example if you're markdown is
My header
---------
The resulting html will look like this:
<h2 id="my-header">My header</h2>
So you can link to it simply by [My link](#my-header)
With the PHP version of Markdown, you can also link headers to fragment identifiers within the page using a syntax like either of the following, as documented here
Header 1 {#header1}
========
## Header 2 ## {#header2}
and then
[Link back to header 1](#header1)
[Link back to header 2](#header2)
Unfortunately this syntax is currently only supported for headers, but at least it could be useful for building a table of contents.
The destination anchor for a link in an HTML page may be any element with an id attribute. See Links on the W3C site. Here's a quote from the relevant section:
Destination anchors in HTML documents
may be specified either by the A
element (naming it with the name
attribute), or by any other element
(naming with the id attribute).
Markdown treats HTML as HTML (see Inline HTML), so you can create your fragment identifiers from any element you like. If, for example, you want to link to a paragraph, just wrap the paragraph in a paragraph tag, and include an id:
<p id="mylink">Lorem ipsum dolor sit amet...</p>
Then use your standard Markdown [My link](#mylink) to create a link to fragment anchor. This will help to keep your HTML clean, as there's no need for extra markup.
For anyone use Visual Studio Team Foundation Server (TFS) 2015, it really does not like embedded <a> or <div> elements, at least in headers. It also doesn't like emoji in headers either:
### 🔧 Configuration 🔧
Lorem ipsum problem fixem.
Gets translated to:
<h3 id="-configuration-">🔧 Configuration 🔧</h3>
<p>Lorem ipsum problem fixem.</p>
And so links should either use that id (which breaks this and other preview extensions in Visual Studio), or remove the emoji:
Here's [how to setup](#-configuration-) //🔧 Configuration 🔧
Here's [how to setup](#configuration) //Configuration
Where the latter version works both online in TFS and in the markdown preview of Visual Studio.
In Pandoc Markdown you can set anchors on arbitrary spans inside a paragraph using syntax [span]{#anchor}, e.g.:
Paragraph, containing [arbitrary text]{#mylink}.
And then reference it as usual: [My link](#mylink).
If you want to reference a whole paragraph then the most straightforward way is to add an empty span right in the beginning of the paragraph:
[]{#mylink}
Paragraph text.