neulab/tldr huggingface dataset:
In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside fields such as title; in CSL YAML databases, pandoc Markdown; and in CSL JSON databases, an HTML-like markup:
<i>...</i> italics
<b>...</b> bold
<span style="font-variant:small-caps;">...</span> or <sc>...</sc> small capitals
<sub>...</sub> subscript
<sup>...</sup> superscript
<span class="nocase">...</span> prevent a phrase from being capitalized as title case
As an alternative to specifying a bibliography file using --bibliography or the YAML metadata field bibliography, you can include the citation data directly in the references field of the document’s YAML metadata. The field should contain an array of YAML-encoded references, for example:
--- references: - type: article-journal id: WatsonCrick1953 author: - family: Watson given: J. D. - family: Crick given: F. H. C. issued: date-parts: - - 1953 - 4 - 25 title: 'Molecular structure of nucleic acids: a structure for deoxyribose nucleic acid' title-short: Molecular structure of nucleic acids container-title: Nature volume: 171 issue: 4356 page: 737-738 DOI: 10.1038/171737a0 URL: https://www.nature.com/articles/171737a0 language: en-GB ...
If both an external bibliography and inline (YAML metadata) references are provided, both will be used.  In case of conflicting ids, the inline references will take precedence.
Note that pandoc can be used to produce such a YAML metadata section from a BibTeX, BibLaTeX, or CSL JSON bibliography:
pandoc chem.bib -s -f biblatex -t markdown pandoc chem.json -s -f csljson -t markdown
Indeed, pandoc can convert between any of these citation formats:
pandoc chem.bib -s -f biblatex -t csljson pandoc chem.yaml -s -f markdown -t biblatex
Running pandoc on a bibliography file with the --citeproc option will create a formatted bibliography in the format of your choice:
pandoc chem.bib -s --citeproc -o chem.html pandoc chem.bib -s --citeproc -o chem.pdf
Capitalization in titles If you are using a bibtex or biblatex bibliography, then observe the following rules:
• English titles should be in title case.  Non-English titles should be in sentence case, and the langid field in biblatex should be set to the relevant language.  (The following values are treated as English: american, british, canadian, english, australian, newzealand, USenglish, or UKenglish.)
• As is standard with bibtex/biblatex, proper names should be protected with curly braces so that they won’t be lowercased in styles that call for sentence case.  For example:
title = {My Dinner with {Andre}}
• In addition, words that should remain lowercase (or camelCase) should be protected:
title = {Spin Wave Dispersion on the {nm} Scale}
Though this is not necessary in bibtex/biblatex, it is necessary with citeproc, which stores titles internally in sentence case, and converts to title case in styles that require it.  Here we protect “nm” so that it doesn’t get converted to “Nm” at this stage.
If you are using a CSL bibliography (either JSON or YAML), then observe the following rules:
• All titles should be in sentence case.
• Use the language field for non-English titles to prevent their conversion to title case in styles that call for this.  (Conversion happens only if language begins with en or is left empty.)
• Protect words that should not be converted to title case using this syntax:
Spin wave dispersion on the <span class="nocase">nm</span> scale
Conference Papers, Published vs. Unpublished For a formally published conference paper, use the biblatex entry type inproceedings (which will be mapped to CSL paper-conference).
For an unpublished manuscript, use the biblatex entry type unpublished without an eventtitle field (this entry type will be mapped to CSL manuscript).
For a talk, an unpublished conference paper, or a poster presentation, use the biblatex entry type unpublished with an eventtitle field (this entry type will be mapped to CSL speech).  Use the biblatex type field to indicate the type, e.g. “Paper”, or “Poster”.  venue and eventdate may be useful too, though eventdate will not be rendered by most CSL styles. Note that venue is for the event’s venue, unlike location which describes the publisher’s location; do not use the latter for an unpublished conference paper.
Specifying a citation style Citations and references can be formatted using any style supported by the Citation Style Language, listed in the Zotero Style Repository. These files are specified using the --csl option or the csl (or citation- style) metadata field.  By default, pandoc will use the Chicago Manual of Style author-date format.  (You can override this default by copying a CSL style of your choice to default.csl in your user data directory.) The CSL project provides further information on finding and editing styles.
The --citation-abbreviations option (or the citation-abbreviations metadata field) may be used to specify a JSON file containing abbreviations of journals that should be used in formatted bibliographies when form="short" is specified.  The format of the file can be illustrated with an example:
{ "default": { "container-title": { "Lloyd's Law Reports": "Lloyd's Rep", "Estates Gazette": "EG", "Scots Law Times": "SLT" } } }
Citations in note styles Pandoc’s citation processing is designed to allow you to move between author-date, numerical, and note styles without modifying the markdown source.  When you’re using a note style, avoid inserting footnotes manually.  Instead, insert citations just as you would in an author-date style—for example,
Blah blah [@foo, p. 33].
The footnote will be created automatically.  Pandoc will take care of removing the space and moving the note before or after the period, depending on the setting of notes-after-punctuation, as described below in Other relevant metadata fields.
In some cases you may need to put a citation inside a regular footnote. Normal citations in footnotes (such as [@foo, p. 33]) will be rendered in parentheses.  In-text citations (such as @foo [p. 33]) will be rendered without parentheses.  (A comma will be added if appropriate.) Thus:
[^1]:  Some studies [@foo; @bar, p. 33] show that frubulicious zoosnaps are quantical.  For a survey of the literature, see @baz [chap. 1].
Raw content in a style To include raw content in a prefix, suffix, delimiter, or term, surround it with these tags indicating the format:
{{jats}}&lt;ref&gt;{{/jats}}
Without the tags, the string will be interpreted as a string and escaped in the output, rather than being passed through raw.
This feature allows stylesheets to be customized to give different output for different output formats.  However, stylesheets customized in this way will not be usable by other CSL implementations.
Placement of the bibliography If the style calls for a list of works cited, it will be placed in a div with id refs, if one exists:
::: {#refs} :::
Otherwise, it will be placed at the end of the document.  Generation of the bibliography can be suppressed by setting suppress-bibliography: true in the YAML metadata.
If you wish the bibliography to have a section heading, you can set reference-section-title in the metadata, or put the heading at the beginning of the div with id refs (if you are using it) or at the end of your document:
last paragraph...
# References
The bibliography will be inserted after this heading.  Note that the unnumbered class will be added to this heading, so that the section will not be numbered.
Including uncited items in the bibliography If you want to include items in the bibliography without actually citing them in the body text, you can define a dummy nocite metadata field and put the citations there:
--- nocite: | @item1, @item2 ...
@item3
In this example, the document will contain a citation for item3 only, but the bibliography will contain entries for item1, item2, and item3.
It is possible to create a bibliography with all the citations, whether or not they appear in the document, by using a wildcard:
--- nocite: | @* ...
For LaTeX output, you can also use natbib or biblatex to render the bibliography.  In order to do so, specify bibliography files as outlined above, and add --natbib or --biblatex argument to pandoc invocation. Bear in mind that bibliography files have to be in either BibTeX (for --natbib) or BibLaTeX (for --biblatex) format.
Other relevant metadata fields A few other metadata fields affect bibliography formatting:
link-citations If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numerical styles only).
lang   The lang field will affect how the style is localized, for example in the translation of labels, the use of quotation marks, and the way items are sorted.  (For backwards compatibility, locale may be used instead of lang, but this use is deprecated.)
A BCP 47 language tag is expected: for example, en, de, en-US, fr- CA, ug-Cyrl.  The unicode extension syntax (after -u-) may be used to specify options for collation (sorting) more precisely.  Here are some examples:
• zh-u-co-pinyin – Chinese with the Pinyin collation.
• es-u-co-trad – Spanish with the traditional collation (with Ch sorting after C).
• fr-u-kb – French with “backwards” accent sorting (with coté sorting after côte).
• en-US-u-kf-upper – English with uppercase letters sorting before lower (default is lower before upper).
notes-after-punctuation If true (the default), pandoc will put footnote citations after following punctuation.  For example, if the source contains blah blah [@jones99]., the result will look like blah blah.[^1], with the note moved after the period and the space collapsed.  If false, the space will still be collapsed, but the footnote will not be moved after the punctuation.
You can use pandoc to produce an HTML + JavaScript slide presentation that can be viewed via a web browser.  There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or reveal.js.  You can also produce a PDF slide show using LaTeX beamer, or slides shows in Microsoft PowerPoint format.
Here’s the Markdown source for a simple slide show, habits.txt:
% Habits % John Doe % March 22, 2005
# In the morning
## Getting up
- Turn off alarm - Get out of bed
## Breakfast
- Eat eggs - Drink coffee
# In the evening
## Dinner
- Eat spaghetti - Drink wine
![picture of spaghetti](images/spaghetti.jpg)
## Going to sleep
- Get in bed - Count sheep
To produce an HTML/JavaScript slide show, simply type
pandoc -t FORMAT -s habits.txt -o habits.html
where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the -s/--standalone option embeds a link to JavaScript and CSS files, which are assumed to be available at the relative path s5/default (for S5), slideous (for Slideous), reveal.js (for reveal.js), or at the Slidy website at w3.org (for Slidy).  (These paths can be changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url variables; see Variables for HTML slides, above.) For DZSlides, the (relatively short) JavaScript and CSS are included in the file by default.
With all HTML slide formats, the --self-contained option can be used to produce a single file that contains all of the data necessary to display the slide show, including linked scripts, stylesheets, images, and videos.
To produce a PDF slide show using beamer, type
pandoc -t beamer habits.txt -o habits.pdf
Note that a reveal.js slide show can also be converted to a PDF by printing it to a file from the browser.
To produce a Powerpoint slide show, type
pandoc habits.txt -o habits.pptx
Structuring the slide show By default, the slide level is the highest heading level in the hierarchy that is followed immediately by content, and not another heading, somewhere in the document.  In the example above, level-1 headings are always followed by level-2 headings, which are followed by content, so the slide level is 2.  This default can be overridden using the --slide- level option.
The document is carved up into slides according to the following rules:
• A horizontal rule always starts a new slide.
• A heading at the slide level always starts a new slide.
• Headings below the slide level in the hierarchy create headings within a slide.  (In beamer, a “block” will be created.  If the heading has the class example, an exampleblock environment will be used; if it has the class alert, an alertblock will be used; otherwise a regular block will be used.)
• Headings above the slide level in the hierarchy create “title slides,” which just contain the section title and help to break the slide show into sections.  Non-slide content under these headings will be included on the title slide (for HTML slide shows) or in a subsequent slide with the same title (for beamer).
• A title page is constructed automatically from the document’s title block, if present.  (In the case of beamer, this can be disabled by commenting out some lines in the default template.)
These rules are designed to support many different styles of slide show. If you don’t care about structuring your slides into sections and subsections, you can just use level-1 headings for all each slide.  (In that case, level-1 will be the slide level.) But you can also structure the slide show into sections, as in the example above.
Note: in reveal.js slide shows, if slide level is 2, a two-dimensional layout will be produced, with level-1 headings building horizontally and level-2 headings building vertically.  It is not recommended that you use deeper nesting of section levels with reveal.js.
Incremental lists By default, these writers produce lists that display “all at once.” If you want your lists to display incrementally (one item at a time), use the -i option.  If you want a particular list to depart from the default, put it in a div block with class incremental or nonincremental.  So, for example, using the fenced div syntax, the following would be incremental regardless of the document default:
::: incremental
::: nonincremental
While using incremental and nonincremental divs are the recommended method of setting incremental lists on a per-case basis, an older method is also supported: putting lists inside a blockquote will depart from the document default (that is, it will display incrementally without the -i option and all at once with the -i option):
> - Eat spaghetti > - Drink wine
Both methods allow incremental and nonincremental lists to be mixed in a single document.
Note: Neither the -i/--incremental option nor any of the methods described here currently works for PowerPoint output.
Inserting pauses You can add “pauses” within a slide by including a paragraph containing three dots, separated by spaces:
# Slide with a pause
content before the pause
content after the pause
Note: this feature is not yet implemented for PowerPoint output.
Styling the slides You can change the style of HTML slides by putting customized CSS files in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or $DATADIR/slideous (for Slideous), where $DATADIR is the user data directory (see --data-dir, above).  The originals may be found in pandoc’s system data directory (generally $CABALDIR/pandoc- VERSION/s5/default).  Pandoc will look there for any files it does not find in the user data directory.
For dzslides, the CSS is included in the HTML file itself, and may be modified there.
All reveal.js configuration options can be set through variables.  For example, themes can be used by setting the theme variable:
-V theme=moon
Or you can specify a custom stylesheet using the --css option.
To style beamer slides, you can specify a theme, colortheme, fonttheme, innertheme, and outertheme, using the -V option:
pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
Note that heading attributes will turn into slide attributes (on a <div> or <section>) in HTML slide formats, allowing you to style individual slides.  In beamer, the only heading attribute that affects slides is the allowframebreaks class, which sets the allowframebreaks option, causing multiple slides to be created if the content overfills the frame.  This is recommended especially for bibliographies:
# References {.allowframebreaks}
Speaker notes Speaker notes are supported in reveal.js and PowerPoint (pptx) output. You can add notes to your Markdown document thus:
::: notes
This is my note.
- It can contain Markdown - like this list
To show the notes window in reveal.js, press s while viewing the presentation.  Speaker notes in PowerPoint will be available, as usual, in handouts and presenter view.
Notes are not yet supported for other slide formats, but the notes will not appear on the slides themselves.
Columns To put material in side by side columns, you can use a native div container with class columns, containing two or more div containers with class column and a width attribute:
:::::::::::::: {.columns} ::: {.column width="40%"} contents... ::: ::: {.column width="60%"} contents... ::: ::::::::::::::
Additional columns attributes in beamer The div containers with classes columns and column can optionally have an align attribute.  The class columns can optionally have a totalwidth attribute or an onlytextwidth class.
:::::::::::::: {.columns align=center totalwidth=8em} ::: {.column width="40%"} contents... ::: ::: {.column width="60%" align=bottom} contents... ::: ::::::::::::::
The align attributes on columns and column can be used with the values top, top-baseline, center and bottom to vertically align the columns.  It defaults to top in columns.
The totalwidth attribute limits the width of the columns to the given value.
:::::::::::::: {.columns align=top .onlytextwidth} ::: {.column width="40%" align=center} contents... ::: ::: {.column width="60%"} contents... ::: ::::::::::::::
The class onlytextwidth sets the totalwidth to \textwidth.
See Section 12.7 of the Beamer User’s Guide for more details.
Frame attributes in beamer Sometimes it is necessary to add the LaTeX [fragile] option to a frame in beamer (for example, when using the minted environment).  This can be forced by adding the fragile class to the heading introducing the slide:
# Fragile slide {.fragile}
All of the other frame attributes described in Section 8.1 of the Beamer User’s Guide may also be used: allowdisplaybreaks, allowframebreaks, b, c, t, environment, label, plain, shrink, standout, noframenumbering.
Background in reveal.js and beamer Background images can be added to self-contained reveal.js slideshows and to beamer slideshows.
For the same image on every slide, use the configuration option background-image either in the YAML metadata block or as a command-line variable.  (There are no other options in beamer and the rest of this section concerns reveal.js slideshows.)
For reveal.js, you can instead use the reveal.js-native option parallaxBackgroundImage.  You can also set parallaxBackgroundHorizontal and parallaxBackgroundVertical the same way and must also set parallaxBackgroundSize to have your values take effect.
To set an image for a particular reveal.js slide, add {data-background- image="/path/to/image"} to the first slide-level heading on the slide (which may even be empty).
In reveal.js’s overview mode, the parallaxBackgroundImage will show up only on the first slide.
Other reveal.js background settings also work on individual slides, including data-background-size, data-background-repeat, data-background- color, data-transition, and data-transition-speed.
To add a background image to the automatically generated title slide, use the title-slide-attributes variable in the YAML metadata block.  It must contain a map of attribute names and values.
See the reveal.js documentation for more details.
For example in reveal.js:
--- title: My Slideshow parallaxBackgroundImage: /path/to/my/background_image.png title-slide-attributes: data-background-image: /path/to/title_image.png data-background-size: contain ---
## Slide One
Slide 1 has background_image.png as its background.
## {data-background-image="/path/to/special_image.jpg"}
Slide 2 has a special image for its background, even though the heading has no content.
EPUB Metadata EPUB metadata may be specified using the --epub-metadata option, but if the source document is Markdown, it is better to use a YAML metadata block.  Here is an example:
--- title: - type: main text: My Book - type: subtitle text: An investigation of metadata creator: - role: author text: John Smith - role: editor text: Sarah Jones identifier: - scheme: DOI text: doi:10.234234.234/33 publisher:  My Press rights: © 2007 John Smith, CC BY-NC ibooks: version: 1.3.4 ...
The following fields are recognized:
identifier Either a string value or an object with fields text and scheme. Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC, ISMN-13, ISBN-A, JP, OLCC.
title  Either a string value, or an object with fields file-as and type, or a list of such objects.  Valid values for type are main, subtitle, short, collection, edition, extended.
creator Either a string value, or an object with fields role, file-as, and text, or a list of such objects.  Valid values for role are MARC relators, but pandoc will attempt to translate the human-readable versions (like “author” and “editor”) to the appropriate marc relators.
contributor Same format as creator.
date   A string value in YYYY-MM-DD format.  (Only the year is necessary.) Pandoc will attempt to convert other common date formats.
lang (or legacy: language) A string value in BCP 47 format.  Pandoc will default to the local language if nothing is specified.
subject A string value or a list of such values.
description A string value.
type   A string value.
format A string value.
relation A string value.
coverage A string value.
rights A string value.
belongs-to-collection A string value.  identifies the name of a collection to which the EPUB Publication belongs.
group-position The group-position field indicates the numeric position in which the EPUB Publication belongs relative to other works belonging to the same belongs-to-collection field.
cover-image A string value (path to cover image).
css (or legacy: stylesheet) A string value (path to CSS stylesheet).
page-progression-direction Either ltr or rtl.  Specifies the page-progression-direction attribute for the spine element.
ibooks iBooks-specific metadata, with the following fields:
• version: (string)
• specified-fonts: true|false (default false)
• ipad-orientation-lock: portrait-only|landscape-only
• iphone-orientation-lock: portrait-only|landscape-only
• binding: true|false (default true)
• scroll-axis: vertical|horizontal|default
The epub:type attribute For epub3 output, you can mark up the heading that corresponds to an EPUB chapter using the epub:type attribute.  For example, to set the attribute to the value prologue, use this markdown:
# My chapter {epub:type=prologue}
Which will result in:
<body epub:type="frontmatter"> <section epub:type="prologue"> <h1>My chapter</h1>
Pandoc will output <body epub:type="bodymatter">, unless you use one of the following values, in which case either frontmatter or backmatter will be output.
epub:type of first section   epub:type of body ─────────────────────────────────────────────── prologue                     frontmatter abstract                     frontmatter acknowledgments              frontmatter copyright-page               frontmatter dedication                   frontmatter credits                      frontmatter keywords                     frontmatter imprint                      frontmatter contributors                 frontmatter other-credits                frontmatter errata                       frontmatter revision-history             frontmatter titlepage                    frontmatter halftitlepage                frontmatter seriespage                   frontmatter foreword                     frontmatter preface                      frontmatter appendix                     backmatter colophon                     backmatter bibliography                 backmatter index                        backmatter
Linked media By default, pandoc will download media referenced from any <img>, <audio>, <video> or <source> element present in the generated EPUB, and include it in the EPUB container, yielding a completely self-contained EPUB.  If you want to link to external media resources instead, use raw HTML in your source and add data-external="1" to the tag with the src attribute.  For example:
<audio controls="1"> <source src="https://example.com/music/toccata.mp3" data-external="1" type="audio/mpeg"> </source> </audio>
If the input format already is HTML then data-external="1" will work as expected for <img> elements.  Similarly, for Markdown, external images can be declared with ![img](url){external=1}.  Note that this only works for images; the other media elements have no native representation in pandoc’s AST and requires the use of raw HTML.
When creating a Jupyter notebook, pandoc will try to infer the notebook structure.  Code blocks with the class code will be taken as code cells, and intervening content will be taken as Markdown cells.  Attachments will automatically be created for images in Markdown cells.  Metadata will be taken from the jupyter metadata field.  For example:
--- title: My notebook jupyter: nbformat: 4 nbformat_minor: 5 kernelspec: display_name: Python 2 language: python name: python2 language_info: codemirror_mode: name: ipython version: 2 file_extension: ".py" mimetype: "text/x-python" name: "python" nbconvert_exporter: "python" pygments_lexer: "ipython2" version: "2.7.15" ---
# Lorem ipsum
**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus bibendum felis dictum sodales.
``` code print("hello") ```
## Pyout
``` code from IPython.display import HTML HTML(""" <script> console.log("hello"); </script> <b>HTML</b> """) ```
## Image
This image ![image](myimage.png) will be included as a cell attachment.
If you want to add cell attributes, group cells differently, or add output to code cells, then you need to include divs to indicate the structure.  You can use either fenced divs or native divs for this.  Here is an example:
:::::: {.cell .markdown} # Lorem
**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus bibendum felis dictum sodales. ::::::
:::::: {.cell .code execution_count=1} ``` {.python} print("hello") ```
::: {.output .stream .stdout} ``` hello ``` ::: ::::::
:::::: {.cell .code execution_count=2} ``` {.python} from IPython.display import HTML HTML(""" <script> console.log("hello"); </script> <b>HTML</b> """) ```
::: {.output .execute_result execution_count=2} ```{=html} <script> console.log("hello"); </script> <b>HTML</b> hello ``` ::: ::::::
If you include raw HTML or TeX in an output cell, use the [raw attribute][Extension: fenced_attribute], as shown in the last cell of the example above.  Although pandoc can process “bare” raw HTML and TeX, the result is often interspersed raw elements and normal textual elements, and in an output cell pandoc expects a single, connected raw block.  To avoid using raw HTML or TeX except when marked explicitly using raw attributes, we recommend specifying the extensions -raw_html- raw_tex+raw_attribute when translating between Markdown and ipynb notebooks.
Note that options and extensions that affect reading and writing of Markdown will also affect Markdown cells in ipynb notebooks.  For example, --wrap=preserve will preserve soft line breaks in Markdown cells; --atx-headers will cause ATX-style headings to be used; and --preserve-tabs will prevent tabs from being turned to spaces.
Pandoc will automatically highlight syntax in fenced code blocks that are marked with a language name.  The Haskell library skylighting is used for highlighting.  Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and LaTeX/PDF output.  To see a list of language names that pandoc will recognize, type pandoc --list-highlight-languages.
The color scheme can be selected using the --highlight-style option.  The default color scheme is pygments, which imitates the default color scheme used by the Python library pygments (though pygments is not actually used to do the highlighting).  To see a list of highlight styles, type pandoc --list-highlight-styles.
If you are not satisfied with the predefined styles, you can use --print- highlight-style to generate a JSON .theme file which can be modified and used as the argument to --highlight-style.  To get a JSON version of the pygments style, for example:
pandoc --print-highlight-style pygments > my.theme
Then edit my.theme and use it like this:
pandoc --highlight-style my.theme
If you are not satisfied with the built-in highlighting, or you want highlight a language that isn’t supported, you can use the --syntax- definition option to load a KDE-style XML syntax definition file.  Before writing your own, have a look at KDE’s repository of syntax definitions.
To disable highlighting, use the --no-highlight option.
Custom styles can be used in the docx and ICML formats.
Output By default, pandoc’s docx and ICML output applies a predefined set of styles for blocks such as paragraphs and block quotes, and uses largely default formatting (italics, bold) for inlines.  This will work for most purposes, especially alongside a reference.docx file.  However, if you need to apply your own styles to blocks, or match a preexisting set of styles, pandoc allows you to define custom styles for blocks and text using divs and spans, respectively.
If you define a div or span with the attribute custom-style, pandoc will apply your specified style to the contained elements (with the exception of elements whose function depends on a style, like headings, code blocks, block quotes, or links).  So, for example, using the bracketed_spans syntax,
[Get out]{custom-style="Emphatically"}, he said.
would produce a docx file with “Get out” styled with character style Emphatically.  Similarly, using the fenced_divs syntax,
Dickinson starts the poem simply:
::: {custom-style="Poetry"} | A Bird came down the Walk--- | He did not know I saw--- :::
would style the two contained lines with the Poetry paragraph style.
For docx output, styles will be defined in the output file as inheriting from normal text, if the styles are not yet in your reference.docx.  If they are already defined, pandoc will not alter the definition.
This feature allows for greatest customization in conjunction with pandoc filters.  If you want all paragraphs after block quotes to be indented, you can write a filter to apply the styles necessary.  If you want all italics to be transformed to the Emphasis character style (perhaps to change their color), you can write a filter which will transform all italicized inlines to inlines within an Emphasis custom-style span.
For docx output, you don’t need to enable any extensions for custom styles to work.
Input The docx reader, by default, only reads those styles that it can convert into pandoc elements, either by direct conversion or interpreting the derivation of the input document’s styles.
By enabling the styles extension in the docx reader (-f docx+styles), you can produce output that maintains the styles of the input document, using the custom-style class.  Paragraph styles are interpreted as divs, while character styles are interpreted as spans.
For example, using the custom-style-reference.docx file in the test directory, we have the following different outputs:
Without the +styles extension:
$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown This is some text.
This is text with an *emphasized* text style. And this is text with a **strengthened** text style.
> Here is a styled paragraph that inherits from Block Text.
And with the extension:
$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
::: {custom-style="First Paragraph"} This is some text. :::
::: {custom-style="Body Text"} This is text with an [emphasized]{custom-style="Emphatic"} text style. And this is text with a [strengthened]{custom-style="Strengthened"} text style. :::
::: {custom-style="My Block Style"} > Here is a styled paragraph that inherits from Block Text. :::
With these custom styles, you can use your input document as a reference- doc while creating docx output (see below), and maintain the same styles in your input and output files.
Pandoc can be extended with custom writers written in Lua.  (Pandoc includes a Lua interpreter, so Lua need not be installed separately.)
To use a custom writer, simply specify the path to the Lua script in place of the output format.  For example:
pandoc -t data/sample.lua
Creating a custom writer requires writing a Lua function for each possible element in a pandoc document.  To get a documented example which you can modify according to your needs, do
pandoc --print-default-data-file sample.lua
Note that custom writers have no default template.  If you want to use --standalone with a custom writer, you will need to specify a template manually using --template or add a new default template with the name default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your user data directory (see Templates).
Some of the document formats pandoc targets (such as EPUB, docx, and ODT) include build timestamps in the generated document.  That means that the files generated on successive builds will differ, even if the source does not.  To avoid this, set the SOURCE_DATE_EPOCH environment variable, and the timestamp will be taken from it instead of the current time. SOURCE_DATE_EPOCH should contain an integer unix timestamp (specifying the number of second since midnight UTC January 1, 1970).
Some document formats also include a unique identifier.  For EPUB, this can be set explicitly by setting the identifier metadata field (see EPUB Metadata, above).
If you use pandoc to convert user-contributed content in a web application, here are some things to keep in mind:
1. Although pandoc itself will not create or modify any files other than those you explicitly ask it create (with the exception of temporary files used in producing PDFs), a filter or custom writer could in principle do anything on your file system.  Please audit filters and custom writers very carefully before using them.
2. If your application uses pandoc as a Haskell library (rather than shelling out to the executable), it is possible to use it in a mode that fully isolates pandoc from your file system, by running the pandoc operations in the PandocPure monad.  See the document Using the pandoc API for more details.
3. Pandoc’s parsers can exhibit pathological performance on some corner cases.  It is wise to put any pandoc operations under a timeout, to avoid DOS attacks that exploit these issues.  If you are using the pandoc executable, you can add the command line options +RTS -M512M -RTS (for example) to limit the heap size to 512MB.
4. The HTML generated by pandoc is not guaranteed to be safe.  If raw_html is enabled for the Markdown input, users can inject arbitrary HTML.  Even if raw_html is disabled, users can include dangerous content in URLs and attributes.  To be safe, you should run all the generated HTML through an HTML sanitizer.
Copyright 2006–2021 John MacFarlane (jgm@berkeley.edu).  Released under the GPL, version 2 or greater.  This software carries no warranty of any kind.  (See COPYRIGHT for full copyright and warranty notices.) For a full list of contributors, see the file AUTHORS.md in the pandoc source code.
The Pandoc source code and all documentation may be downloaded from <https://pandoc.org>.
BAT(1)                       General Commands Manual                      BAT(1)
bat - a cat(1) clone with syntax highlighting and Git integration.
bat [OPTIONS] [FILE]...
bat cache [CACHE-OPTIONS] [--build|--clear]
bat prints the syntax-highlighted content of a collection of FILEs to the terminal. If no FILE is specified, or when FILE is '-', it reads from standard input.
bat supports a large number of programming and markup languages.  It also communicates with git(1) to show modifications with respect to the git index.  bat automatically pipes its output through a pager (by default: less).
Whenever the output of bat goes to a non-interactive terminal, i.e. when the output is piped into another process or into a file, bat will act as a drop-in replacement for cat(1) and fall back to printing the plain file contents.
General remarks: Command-line options like '-l'/'--language' that take values can be specified as either '--language value', '--language=value', '-l value' or '-lvalue'.
-A, --show-all
Show non-printable characters like space, tab or newline. Use '--tabs' to control the width of the tab-placeholders.
-p, --plain
Only show plain style, no decorations. This is an alias for '--style=plain'. When '-p' is used twice ('-pp'), it also disables automatic paging (alias for '--style=plain --pager=never').
-l, --language <language>
Explicitly set the language for syntax highlighting. The language can be specified as a name (like 'C++' or 'LaTeX') or possible file extension (like 'cpp', 'hpp' or 'md'). Use '--list-languages' to show all supported language names and file extensions.
-H, --highlight-line <N:M>...
Highlight the specified line ranges with a different background color. For example:
--highlight-line 40 highlights line 40
--highlight-line 30:40 highlights lines 30 to 40
--highlight-line :40 highlights lines 1 to 40
--highlight-line 40: highlights lines 40 to the end of the file
--file-name <name>...
Specify the name to display for a file. Useful when piping data to bat from STDIN when bat does not otherwise know the filename. Note that the provided file name is also used for syntax detection.
-d, --diff
Only show lines that have been added/removed/modified with respect to the Git index. Use '--diff-context=N' to control how much context you want to see.
--diff-context <N>...
Include N lines of context around added/removed/modified lines when using '--diff'.
--tabs <T>
Set the tab width to T spaces. Use a width of 0 to pass tabs through directly
--wrap <mode>
Specify the text-wrapping mode (*auto*, never, character). The '--terminal-width' option can be used in addition to control the output width.
--terminal-width <width>
Explicitly set the width of the terminal instead of determining it automatically. If prefixed with '+' or '-', the value will be treated as an offset to the actual terminal width. See also: '--wrap'.
-n, --number
Only show line numbers, no other decorations. This is an alias for '--style=numbers'
--color <when>
Specify when to use colored output. The automatic mode only enables colors if an interactive terminal is detected. Possible values: *auto*, never, always.
--italic-text <when>
Specify when to use ANSI sequences for italic text in the output. Possible values: always, *never*.
--decorations <when>
Specify when to use the decorations that have been specified via '--style'. The automatic mode only enables decorations if an interactive terminal is detected. Possible values: *auto*, never, always.
-f, --force-colorization
Alias for '--decorations=always --color=always'. This is useful if the output of bat is piped to another program, but you want to keep the colorization/decorations.
--paging <when>
Specify when to use the pager. To disable the pager, use '--paging=never' or its alias, -P. To disable the pager permanently, set BAT_PAGER to an empty string. To control which pager is used, see the '--pager' option. Possible values: *auto*, never, always.
--pager <command>
Determine which pager is used. This option will override the PAGER and BAT_PAGER environment variables. The default pager is 'less'. To control when the pager is used, see the '--paging' option. Example: '--pager "less -RF"'.
-m, --map-syntax <glob-pattern:syntax-name>...
Map a glob pattern to an existing syntax name. The glob pattern is matched on the full path and the filename. For example, to highlight *.build files with the Python syntax, use -m '*.build:Python'. To highlight files named '.myignore' with the Git Ignore syntax, use -m '.myignore:Git Ignore'.  Note that the right-hand side is the *name* of the syntax, not a file extension.
--theme <theme>
Set the theme for syntax highlighting. Use '--list-themes' to see all available themes.  To set a default theme, add the '--theme="..."' option to the configuration file or export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
--list-themes
Display a list of supported themes for syntax highlighting.
--style <style-components>
Configure which elements (line numbers, file headers, grid borders, Git modifications, ..) to display in addition to the file contents. The argument is a comma-separated list of components to display (e.g. 'numbers,changes,grid') or a pre-defined style ('full').  To set a default style, add the '--style=".."' option to the configuration file or export the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible values: *auto*, full, plain, changes, header, grid, rule, numbers, snip.
-r, --line-range <N:M>...
Only print the specified range of lines for each file. For example:
--line-range 30:40 prints lines 30 to 40
--line-range :40 prints lines 1 to 40
--line-range 40: prints lines 40 to the end of the file
-L, --list-languages
Display a list of supported languages for syntax highlighting.
-u, --unbuffered
This option exists for POSIX-compliance reasons ('u' is for 'unbuffered'). The output is always unbuffered - this option is simply ignored.
Print this help message.
-V, --version
Show version information.
<FILE>...
Files to print and concatenate. Use a dash ('-') or no argument at all to read from standard input.
cache - Modify the syntax-definition and theme cache.
bat can also be customized with a configuration file. The location of the file is dependent on your operating system. To get the default path for your system, call:
bat --config-file
Alternatively, you can use the BAT_CONFIG_PATH environment variable to point bat to a non-default location of the configuration file.
To generate a default configuration file, call:
bat --generate-config-file
bat supports Sublime Text .sublime-syntax language files, and can be customized to add additional languages to your local installation. To do this, add the .sublime-syntax language files to `$(bat --config- dir)/syntaxes` and run `bat cache --build`.
mkdir -p "$(bat --config-dir)/syntaxes" cd "$(bat --config-dir)/syntaxes"
# Put new '.sublime-syntax' language definition files # in this folder (or its subdirectories), for example: git clone https://github.com/tellnobody1/sublime-purescript-syntax
# And then build the cache. bat cache --build
Once the cache is built, the new language will be visible in `bat --list- languages`. If you ever want to remove the custom languages, you can clear the cache with `bat cache --clear`.
Similarly to custom languages, bat supports Sublime Text .tmTheme themes. These can be installed to `$(bat --config-dir)/themes`, and are added to the cache with `bat cache --build`.
For more information and up-to-date documentation, visit the bat repo: https://github.com/sharkdp/bat
NPM(1)                                                                    NPM(1)
npm - javascript package manager
Synopsis npm <command> [args]
Description npm is the package manager for the Node JavaScript platform.  It puts modules in place so that node can find them, and manages dependency conflicts intelligently.
It is extremely configurable to support a variety of use cases.  Most commonly, you use it to publish, discover, install, and develop node programs.
Run npm help to get a list of available commands.
Important npm comes preconfigured to use npm's public registry at https://registry.npmjs.org by default. Use of the npm public registry is subject to terms of use available at https://docs.npmjs.com/policies/terms.
You can configure npm to use any compatible registry you like, and even run your own registry. Use of someone else's registry is governed by their terms of use.
Introduction You probably got npm because you want to install stuff.
The very first thing you will most likely want to run in any node program is npm install to install its dependencies.
You can also run npm install blerg to install the latest version of "blerg".  Check out npm help install for more info.  It can do a lot of stuff.
Use the npm search command to show everything that's available in the public registry.  Use npm ls to show everything you've installed.
Dependencies If a package lists a dependency using a git URL, npm will install that dependency using the git https://github.com/git-guides/install-git command and will generate an error if it is not installed.
If one of the packages npm tries to install is a native node module and requires compiling of C++ Code, npm will use node-gyp https://github.com/nodejs/node-gyp for that task.  For a Unix system, node-gyp https://github.com/nodejs/node-gyp needs Python, make and a buildchain like GCC. On Windows, Python and Microsoft Visual Studio C++ are needed. For more information visit the node-gyp repository https://github.com/nodejs/node-gyp and the node-gyp Wiki https://github.com/nodejs/node-gyp/wiki.
Directories See npm help folders to learn about where npm puts stuff.
In particular, npm has two modes of operation:
• local mode: npm installs packages into the current project directory, which defaults to the current working directory.  Packages install to ./node_modules, and bins to ./node_modules/.bin.
• global mode: npm installs packages into the install prefix at $npm_config_prefix/lib/node_modules and bins to $npm_config_prefix/bin.
Local mode is the default.  Use -g or --global on any command to run in global mode instead.
Developer Usage If you're using npm to develop and publish your code, check out the following help topics:
• json: Make a package.json file.  See npm help package.json.
• link: Links your current working code into Node's path, so that you don't have to reinstall every time you make a change.  Use npm help npm link to do this.
• install: It's a good idea to install things if you don't need the symbolic link.  Especially, installing other peoples code from the registry is done via npm help install
• adduser: Create an account or log in.  When you do this, npm will store credentials in the user config file config file.
• publish: Use the npm help publish command to upload your code to the registry.
Configuration npm is extremely configurable.  It reads its configuration options from 5 places.
• Command line switches: Set a config with --key val.  All keys take a value, even if they are booleans (the config parser doesn't know what the options are at the time of parsing).  If you do not provide a value (--key) then the option is set to boolean true.
• Environment Variables: Set any config by prefixing the name in an environment variable with npm_config_.  For example, export npm_config_key=val.
• User Configs: The file at $HOME/.npmrc is an ini-formatted list of configs.  If present, it is parsed.  If the userconfig option is set in the cli or env, that file will be used instead.
• Global Configs: The file found at ./etc/npmrc (relative to the global prefix will be parsed if it is found.  See npm help prefix for more info on the global prefix.  If the globalconfig option is set in the cli, env, or user config, then that file is parsed instead.
• Defaults: npm's default configuration options are defined in lib/utils/config-defs.js.  These must not be changed.
See npm help config for much much more information.
Contributions Patches welcome!
If you would like to help, but don't know what to work on, read the contributing guidelines https://github.com/npm/cli/blob/latest/CONTRIBUTING.md and check the issues list.
Bugs When you find issues, please report them: https://github.com/npm/cli/issues
Please be sure to follow the template and bug reporting guidelines.
Feature Requests Discuss new feature ideas on our discussion forum:
• https://github.com/npm/feedback
Or suggest formal RFC proposals:
• https://github.com/npm/rfcs
See Also • npm help help
• npm help package.json
• npm help npmrc
• npm help config
• npm help install
• npm help prefix
• npm help publish
EXPR(1P)                    POSIX Programmer's Manual                   EXPR(1P)
expr — evaluate arguments as an expression
expr operand...
The expr utility shall evaluate an expression and write the result to standard output.
The single expression evaluated by expr shall be formed from the operand operands, as described in the EXTENDED DESCRIPTION section. The application shall ensure that each of the expression operator symbols:
(  )  |  &  =  >  >=  <  <=  !=  +  -  *  /  %  :
and the symbols integer and string in the table are provided as separate arguments to expr.