Package: pandoc-inline-headers
Pandoc filter to render headers as inline headers in html, docx and odt
conversion, while keeping header ids (and cross-references).Even if it can used as the only pandoc filter, it is intended to be used
in cascade afterpandoc-crossref.Inline header delimiters, as well as inline numbering and header styles,
can be customized globally and/or for a specific chapter.NEW:With the additional crossref-ordered-list filter (used in
cascadebeforepandoc-crossref), it can handle also markdown ordered
lists, converting them into “native” pandoc-crossref ordered lists, that
can be referenced by adding the item’s number or letter to section
identifier (like@sec:mysection:a).Here is an example of the filter in action with html preview:and here is an example of conversion of the same example text to odt:1. Installation1.1. Python Packagesudopip3installpandoc-inline-headersor, if you want to install as user:pip3install--userpandoc-inline-headersbut then check if your PATH contains also your user installation
directory).Note: pip and pip3 are two different applications; pip3 is for
python 3.x and it is the one you need to use to install this package.1.2. (Highly) Recommended Pandoc FiltersPandoc-crossrefis
not necessary buthighly recommended, becausewithout it, you
cannot exploit all the features of pandoc-inline-headers. To
install it, you may just download the latest release file from the
correspondinggithub
page, and
install thepandoc-crossrefbinary to a directory included in
your PATH (likeusr/local/binor the like).Moreover, if you want to convert to odt, you need also a patched
version odt-custom-styles lua filter byjzeneto– see my pull requesthere. You
have to download bothodt-custom-styles.luaandutil.luaand put them in your lua filters directory (tipically,~/.pandoc/filters/).2. Usage2.1. Basics2.1.1. YAML Configuration Variables---numberSections:truelinkReferences:truesectionsDepth:3secHeaderDelim:".&#9;"inlineHeaderLevel:2---The first four variables are relative to thepandoc-crossreffilter:
we activate section numbering, automatic creation of reference links,
third level section depth, and a section header number delimiter (period
followed by tab) that will be useful when converting to docx or odt
formats (note that the ‘tab’ character must be written as the
corresponding html character code –&#9;– otherwise it is ignored
bypandoc-crossref).The last variable is the one that ‘activates’inline-section-headers. It means that all headers, whose level is 2
or higher, will be rendered as inline headers. Such parameter
automatically activates also thecrossref-ordered-listfilter
(see below), that can be activated also (if for some reason you do not
want inline section headers but you do want ordered lists converted topandoc-crossrefsections) by settingcrossrefOrderedList: true.Of course you can choose level 3, 4, etc. as inlineHeaderLevel. Instead,
putting values below 2 will not produce any effect – so first level
headers cannot be rendered as inline headers (this feature may be added
in the future).And, of course, you can use different values forpandoc-crossrefvariables (you should refer to itsdocumentation): the
values shown above are just an example of a typical usage ofpandoc-inline-headerstogether withpandoc-crossref.2.1.2. Markdown SyntaxJust write your markdown documents as usual, keeping in mind that all
headers, whose level is equal to or greater than theinlineHeaderLevelvariable, will be rendered as inline headers.Section identifiers (like{#sec:my_section}) will be kept, and
cross-references (like@sec:my_section) will be correctly rendered
even if they refer to inline headers.Comments within the text or between section header and section text
(like<!--comment-->) are kept but ignored.You can use also empty headers, like:###I'm a section without headerthat will be rendered (if you usepandoc-crossref) as follows:1.2.3. I’m a section without headereven if in such cases it is recommended to put a unique section
identifier:### {#sec:no_header_section}I'm a section without headerAs for ordered lists, if you use crossref-ordered-list filterbeforepandoc-crossref and pandoc-inline-headers, they can be rendered and
referenced through pandoc-crossref.If you want to reference an ordered list item, you can just use the
automatically created identifier (#PARENT_SECTION_ID:ITEM_NUMBER,
f.e.#sec:my_section:a), but, if you want acustom identifier that
does not changeif you change the position of the list item or you add
other items), you can set it with a syntax likea. {#sec:my_custom_id} item text.Here is an example of the code with html preview:Please note the use ofsectionsDepthto choose at which level
ordered list numbers/letters have to be rendered without the parent
section number(s) - i.e.a. iteminstead of1.1.a. item- and
also note that, when refencing ordered list items, parent section
numbers are always included, regardless of thesectionsDepthvalue
(exactly as one may expect).2.1.3. Markdown Preview in EditorIf you use a markdown preview plugin in your favourite text editor, you
should include the three filterscrossref-ordered-list,pandoc-crossrefandpandoc-inline-headers(in this precise
order) in pandoc rendering settings.You should choose a markdown preview plugin that does not modify the
markdown code before passing it to pandoc, otherwise you may get wrong
or misleading output. F.e. markdown-preview-plus for Atom seem to work
correctly with pandoc-inline-headers.You can also usemarkdown-preview-enhanced,
thatsince version 0.16.2works well with pandoc-inline-headers.2.1.4. Converting to html, docx, odtPandoc-inline-headers must be used in cascade afterpandoc-crossref(and beforeodt-custom-styles.lua, when converting to odt), while
crossref-ordered-list must be put before it.a) HTMLA typical command to convert to html would be:pandoc -p -t html \
  --filter=crossref-ordered-list \
  --filter=pandoc-crossref \
  --filter=pandoc-inline-headers \
  --o test.html test.mdb) docxTo convert to docx you have to do first:pandoc -p -t docx \
  --filter=crossref-ordered-list \
  --filter=pandoc-crossref \
  --filter=pandoc-inline-headers \
  --o test.docx -p test.mdPlease note the-p(or--preserve-tabs) option, needed if you
need tabs in your output documentThen you should editexample.docxand change the custom paragraph
styles created by the filter, that are named ‘Customlist 1 start’,
‘Customlist 1’, ‘Customlist 2 start’, ‘Customlist 2’, and so on (styles
with ‘start’ at the end of the name are applied to the first paragraph
of a section; styles without ‘start’ are applied to the following
paragraphs).You may use appropriate tab values in paragraph styles, that, together
with the section header number delimiter suggested above (period
followed by tab, or.&#9;) may lead to nice results like in the
example images at the beggining of this README.When you are satisfied of your model, just save it (say, astest_model.docx) and use it in your pandoc command:pandoc -p -t docx \
  --filter=crossref-ordered-list \
  --filter=pandoc-crossref \
  --filter=pandoc-inline-headers \
  --reference-doc=test_model.docx \
  --o test.docx -p test.mdc) odtConverting to odt is a little bit more complicated, since pandoc does
not support odt custom styles yet (there is anopen
issueabout that on
github). There is alua filter written by
jzenetoas a
workaround for such issue, but such filter:does not support tabs (so that you will have to use my patched
version – see installation instructions above) anddoes not support the creation of custom styles if they are not found
in the model, so you will have to create your model document first,
and manually add the needed custom styles (named like explained above
for docx conversion).Afterwards, you will be able to convert to odt in this way:pandoc -p -t odt \
  --filter=crossref-ordered-list \
  --filter=pandoc-crossref \
  --filter=pandoc-inline-headers \
  --lua-filter=odt-custom-styles.lua \
  --reference-doc=test_model.odt \
  --o test.odt -p test.md2.2. Advanced Use2.2.1. Customization of inline header delimiters and stylesThe most important advanced feature you may need is customization of
inline header delimiters and styles. This may be done globally (by
putting the variable value in YAML metadata at the beginning of the
markdown document, likeinlineHeaderDelim: ':') and/or for the
subsections of a specific ‘main’ section header – i.e., if you set
inlineHeaderLevel to 2, a ‘main’ section header is a level 1 header
(example:# my level 1 section {#sec:my_secinlineHeaderDelim=":"inlineHeaderStyle="bold"}).inlineHeaderDelimSequence of characters put after an inline section header and before
section text. If the section header title is empty, it is not rendered.
Setting a different value (say, colon ‘:’) only for a specific section
may be useful if, for example, its subsections contain definitions (like
in the example images at the beginning of this README).default value:‘.’inlineHeaderStyleStyle for inline headers.possible values:‘plain’, ‘normal’, ‘standard’ (will be all rendered as plain text)‘emph’, ‘emphasis’, ‘italic’ (will be all rendered as italic)‘bold’, ‘strong’ (will be all rendered as bold)default value:‘emph’inlineHeaderNumStyleStyle for inline header numbers. Used only if you use also
pandoc-crossref, and only if you set a different value forsecHeaderDelimand forchapDelim(for instance, ifchapDelimis set to the default value., you have to setsecHeaderDelimto, for example,.&nbsp;or.&#9;as suggested above)possible values:same as inlineHeaderStyledefault value:‘plain’inlineHeaderParStyle, inlineHeaderParStyleStartPandoc uses two paragraphs: one at the beginning of the text, one for
the follow-on paragraphs (usually, first paragraph, text body), to
follow the convention that first paragraphs have no leading indent. The
same happens with pandoc-inline-headers.py. Style names will be
generated as follows: To override the standard default values, you can
add one or both of these parameters. They will be rendered according to
the following convention:{inlineHeaderParStyle} {level} {inlineHeaderParStyleStart}
{inlineHeaderParStyle} {level}Therefore, The actual name of the styles, using{inlineHeaderParStyle="Mystyle" inlineHeaderParStyleStart="first"}will be, when converted:# heading 1Mystyle 1 firstMystyle 1## Heading 2Mystyle 2 firstMystyle 2### Heading 3Mystyle 3 firstMystyle 3etc.default values:‘Customlist’ ‘start’2.2.2. Ordered listsAs for ordered lists (likea) ... b) ...), you may ‘use’ them even
without thecrossref-ordered-listfilter, but please keep in mind
that,because of apandoc
bug/issue, they
cannot be rendered in odt or in docx conversionwith a customliststyle, but only with a customparagraphstyle; but with ordered lists,
paragraph style customization is of little use, because, among other
things,paragraphsyle indents are overrided byliststyle indents
(so you will always get the indents set in the default list style,
regardless of the level/indentation of the “parent” section).In other words, you cannot customize standard ordered list styles in
docx and odt; this is the reason why it is preferable to render them as
“native” pandoc-crossref lists (so you can even reference them, as
explained in theBasics section)