Contents

• Markdown Reference
• Vs Code Markdown Memo

Making a bibliography

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages. Using Markdown is different than using a WYSIWYG editor. What is Markdown? You might be wondering, what the heck is Markdown anyway? Markdown is a lightweight markup language.It allows you to style a digital text document using typical formatting techniques: for example, headings, emphasis, lists, images, and links. For about.GitLab.com we use kramdown, which is an advanced Markdown engine with a lot of interesting features that most of the other engines don't have, such as inline attribute lists (IALs), which enable easy styling beyond the standard Markdown options. VS Code supports Markdown files out of the box. You just start writing Markdown text, save the file with the.md extension and then you can toggle the visualization of the editor between the code and the preview of the Markdown file; obviously, you can also open an existing Markdown file and start working with it.

Markdown-memo uses bibtex via pandoc to generate a bibliography for your document. We’ve made this even simpler by allowing the user to create a simple text file to generate the necessary bibtex .bib file using the markdown2bib script. Markdown-memo looks for any bibs/*.txt files and uses markdown2bib to combine them and create bibs/mybib.bib in bibtex format. This is later used by pandoc when creating tex (rightarrow) pdf or html.

The bibs/*.txt should be plain text with a single reference per line, with each reference in a style that loosely follows the American Psychological Association (APA), which is commonly used in humanities. Currently four types of references are supported: article, book, incollection, and misc. The journal or book titles need to be in markdown-style emphasis, meaning *Set Within Asterixis*. Also note that for works in a collection, you need to use the word “In” in the right place, like in the reference by Quine below. The rest of the syntax tries to be forgiving. If you want to add a note to appear at the end of the reference, put it at the end within [square brackets] like the work by Plato below.

For example, the mybib.txt file in this document is

If you do not want to use simplified txt files to generate bibtex, and you want to write your own bibtex, then simply remove any bibs/*.txt files and write a file called bibs/mybib.bib.

If you do not need a bibliography, set

in meta.yaml, and then these scripts and programs are not run.

Doing citations

Citations start with an @-sign, and can be used inline, like:

which produces:

Miller (2014) argues that we should get real.

Inside a caption, you may want to end it with the citation in parentheses like this:

which produces:

Blah blah blah (Feynman, 1963).

Typically, I find it better to leave citations³ in footnotes to keep from cluttering the main text. Let’s try citing various kinds of references. Feynman said some important things⁴. But everything is a footnote to Plato⁵. Van⁶ is a cool cat too. A reference with more than 4 authors should be automatically shortened with et al.⁷

In order for a References section to be generated per html page, you need to add a special html comment near the end of your Markdown file for that page:

Pages without such a comment will not get an automatic References section, but the complete pdf document will automatically still have a complete References section at the end as long as

is set in meta.yaml.

References

1. University of California, Santa Cruz / ryan.reece@gmail.com / http://rreece.github.io↩︎

2. Joe University, Joeville / jane@joe.edu / http://jane.joe.edu↩︎

3. Quine (1969).↩︎

4. Feynman (1965).↩︎

5. Plato (2000).↩︎

6. van Fraassen (1980).↩︎

7. Guest, D. et al. (2016).↩︎

Table of Contents

You can add a table of contents using the toc option and specify the depth of headers that it applies to using the toc_depth option. For example:

If the table of contents depth isn’t explicitly specified then it defaults to 3 (meaning that all level 1, 2, and 3 headers will be included in the table of contents).

Floating TOC

You can specify the toc_float option to float the table of contents to the left of the main document content. The floating table of contents will always be visible even when the document is scrolled. For example:

You may optionally specify a list of options for the toc_float parameter which control it’s behavior. Options include:

• collapsed (defaults to TRUE) controls whether the table of contents appers with only the top-level (e.g. H2) headers. When collapsed the table of contents is automatically expanded inline when necessary.

• smooth_scroll (defaults to TRUE) controls whether page scrolls are animated when table of contents items are navigated to via mouse clicks.

For example:

Requirements

Support for floating table of contents is only available in very recent versions of the rmarkdown package. You can install the most current version as follows:

Markdown Reference

Section Numbering

You can add section numbering to headers using the number_sections option:

Vs Code Markdown Memo

Note that if you do choose to use the number_sections option you will likely also want to use # (H1) headers in your document as ## (H2) headers will include a decimal point.