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.
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 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.
:::
I have a Jekyll site that uses kramdown for markdown. In _config.yml I have the following setting that ensures that only <h2> and <h3> elements show up in the automatically generated table of contents:
kramdown:
toc_levels: "2,3"
This works fine, but on some pages I would like to include <h4> elements in the TOC as well, while retaining the existing <h2> and <h3> configuration on other pages. Is this possible?
On any page I can access the _config.yml definitions like this:
{{ site.kramdown.toc_levels }}
Is there a way to set the value of the toc_levels on a page?
I looked through the codes. It appears page-level settings are not possible for Kramdown at this moment. You are left with {:.no_toc} option to suppress unexpected tags.
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.