# Writing content with Markdown, LaTeX, and Shortcodes

Content can be written using Markdown, LaTeX math, Shortcodes. Shortcodes are plugins which are bundled with Academic or inherited from Hugo. Additionally, HTML may be written in Markdown documents for advanced formatting.

This article gives an overview of the most common formatting options, including features that are exclusive to Academic.

## Heading 2


## Emphasis

Italics with _underscores_.

Bold with **asterisks**.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough with ~~two tildes~~.


## Ordered lists

1. First item
2. Another item


## Unordered lists

* First item
* Another item


### Todo lists

Todo lists can be written in Academic by using the standard Markdown syntax:

- [x] Write math example
- [x] Write diagram example
- [ ] Do something else


renders as

• Write math example
• Write diagram example
• Do something else

## Images

Images may be added to a page by either placing them in your static/img/ media library or in your page's folder, and then referencing them using one of the following notations:

A figure from your static/img/ media library:

{{< figure library="true" src="image.jpg" title="A caption" lightbox="true" >}}


A figure within a page's folder (e.g. content/post/hello/) :

{{< figure src="image.jpg" title="A caption" lightbox="true" >}}


A numbered figure with caption:

{{< figure src="image.jpg" title="A caption" numbered="true" lightbox="true" >}}


A general image:

![alternative text for search engines](/img/image.jpg)


To add an image gallery to a page bundle:

1. Create a gallery album folder within your page bundle (i.e. within your page's own folder)
3. Paste {{< gallery album="<ALBUM FOLDER>" >}} where you would like the gallery to appear in the page content, changing the album parameter to match the name of your album folder

gallery_item:
- album: <ALBUM FOLDER>
image: <IMAGE NAME>.jpg
caption: Write your image caption here


Alternatively, create an image gallery with images from the internet or your static/img/ media library:

1. Add gallery images to within your static/img/ media library folder
2. Reference your images at the end of the front matter of a content file in the form:

gallery_item:
- album: gallery
image: boards.jpg
caption: A caption
- album: gallery
caption: Another caption

3. Display the gallery somewhere within your page content by using {{< gallery >}}

For docs pages (i.e. pages using the courses and documentation layout), gallery images must be placed in the static/ media library using the second approach (due to limitations of Hugo).

## Videos

The following kinds of video may be added to a page.

Local video file

Videos may be added to a page by either placing them in your static/img/ media library or in your page's folder, and then referencing them using one of the following notations.

A video from your static/img/ media library:

{{< video library="1" src="my_video.mp4" controls="yes" >}}


A video within a page's folder (e.g. content/post/hello/):

{{< video src="my_video.mp4" controls="yes" >}}


{{< youtube w7Ft2ymGmfc >}}


Vimeo:

{{< vimeo 146022717 >}}

[I'm a link](https://www.google.com)
[A post]({{< ref "/post/my-page-name/index.md" >}})
[A publication]({{< ref "/publication/my-page-name/index.md" >}})
[A project]({{< ref "/project/my-page-name/index.md" >}})
[A relative link from one post to another post]({{< relref "../my-page-name/index.md" >}})
[Scroll down to a page section with heading *Hi*](#hi)


To enable linking to a file, such as a PDF, first place the file in your static/files/ folder and then link to it using the following form:

{{% staticref "files/cv.pdf" "newtab" %}}Download my CV{{% /staticref %}}


The optional "newtab" argument for staticref will cause the link to be opened in a new tab.

### Tags and Categories

Use {{< list_tags >}} to provide a list of linked tags or {{< list_categories >}} to provide a list of linked categories.

## Emojis

See the Emoji cheat sheet for available emoticons. The following serves as an example, but you should remove the spaces between each emoji name and pair of semicolons:

I : heart : Academic : smile :


## Blockquote

> This is a blockquote.


This is a blockquote.

## Highlight quote

This is a {{< hl >}}highlighted quote{{< /hl >}}.


This is a highlighted quote.

## Mention a user

To mention someone, type {{% mention "username" %}} where username corresponds to a user account in Academic.

## Footnotes

I have more [^1] to say.

[^1]: Footnote example.


I have more 1 to say.

## Embed Documents

The following kinds of document may be embedded into a page.

To embed Google Documents (e.g. slide deck), click File > Publish to web > Embed in Google Docs and copy the URL within the displayed src="..." attribute. Then paste the URL in the form:

{{< gdocs src="https://docs.google.com/..." >}}


## Diagrams

Academic supports a Markdown extension for diagrams. You can enable this feature by toggling the diagram option in your config/_default/params.toml file or by adding diagram: true to your page front matter. Then insert your Mermaid diagram syntax within a mermaid code block as seen below and that's it. Note: Academic v4.4.0+ is required to make diagrams.

An example flowchart:

mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;



renders as

graph TD;
A-->B;
A-->C;
B-->D;
C-->D;


An example sequence diagram:

mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
Bob-->John: Jolly good!



renders as

sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
Bob-->John: Jolly good!


An example Gantt diagram:

mermaid
gantt
dateFormat  YYYY-MM-DD
section Section
Another task     :after a1  , 20d
section Another
Task in sec      :2014-01-12  , 12d



renders as

gantt
dateFormat  YYYY-MM-DD
section Section
Another task     :after a1  , 20d
section Another
Task in sec      :2014-01-12  , 12d


More advanced diagrams can be created in the open source draw.io editor. The editor has support for almost any type of diagram, from simple to complex. A diagram can be easily embedded in Academic by choosing File > Embed > SVG in the draw.io editor and pasting the generated code into your page.

Alternatively, a diagram can be exported as an image from any drawing software, or a document/slide containing a diagram can be embedded.

## Code highlighting

Pass the language of the code, such as python, as a parameter after three backticks:

python
# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))



Result:

# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))


### Highlighting options

The Academic theme uses highlight.js for source code highlighting, and highlighting is enabled by default for all pages. However, several configuration options are supported that allow finer-grained control over highlight.js.

The following table lists the supported options for configuring highlight.js, along with their expected type and a short description. A "yes" in the config.toml column means the value can be set globally in config.toml, and a "yes" in the preamble column means that the value can be set locally in a particular page's preamble.

optiontypedescriptionconfig.tomlpreamble
highlightbooleanenable/disable highlightingyesyes
highlight_languagesslicechoose additional languagesyesno
highlight_stylestringchoose a highlighting styleyesno

#### Option highlight

The highlight option allows enabling or disabling the inclusion of highlight.js, either globally or for a particular page. If the option is unset, it has the same effect as if you had specified highlight = true. That is, the highlight.js javascript and css files will be included in every page. If you'd like to only include highlight.js files on pages that actually require source code highlighting, you can set highlight = false in params.toml, and then override it by setting highlight: true in the preamble of any pages that require source code highlighting. Conversely, you could enable highlighting globally, and disable it locally for pages that do not require it. Here is a table that shows whether highlighting will be enabled for a page, based on the values of highlight set in params.toml and/or the page's preamble.

config.tomlpage front matterhighlighting enabled for page?
unset or trueunset or trueyes
unset or truefalseno
falseunset or falseno
falsetrueyes

#### Option highlight_languages

The highlight_languages option allows you to specify additional languages that are supported by highlight.js, but are not considered "common" and therefore are not supported by default. For example, if you want source code highlighting for Go and clojure in all pages, set highlight_languages = ["go", "clojure"] in params.toml. If, on the other hand, you want to enable a language only for a specific page, you can set highlight_languages in that page's preamble.

The highlight_languages options specified in config.toml and in a page's preamble are additive. That is, if params.toml contains, highlight_languages = ["go"] and the page's preamble contains highlight_languages: ["ocaml"], then javascript files for both go and ocaml will be included for that page.

If the highlight_languages option is set, then the corresponding javascript files will be served from the cdnjs server. To see a list of available languages, visit the cdnjs page and search for links with the word "languages".

The highlight_languages option provides an easy and convenient way to include support for additional languages to be severed from a CDN. If serving unmodified files from cdnjs doesn't meet your needs, you can include javascript files for additional language support via one of the methods described in the customization guide.

#### Option highlight_style

The highlight_style option allows you to select an alternate css style for highlighted code. For example, if you wanted to use the solarized-dark style, you could set highlight_style = "solarized-dark" in params.toml.

If the highlight_style option is unset, the default is to use the file /css/highlight.min.css, either the one provided by the Academic theme, or else the one in your local static directory. The /css/highlight.min.css file provided by Academic is equivalent to the github style from highlight.js.

If the highlight_style option is set, then /css/highlight.min.css is ignored, and the corresponding css file will be served from the cdnjs server. To see a list of available styles, visit the cdnjs page and search for links with the word "styles".

See the highlight.js demo page for examples of available styles.

Not all styles listed on the highlight.js demo page are available from the cdnjs server. If you want to use a style that is not served by cdnjs, just leave highlight_style unset, and place the corresponding css file in /static/css/highlight.min.css.
If you don’t want to change the default style that ships with Academic but you do want the style file served from the cdnjs server, set highlight_style = "github" in params.toml.

The highlight_style option is only recognized when set in params.toml. Setting highlight_style in your page's preamble has no effect.

## Jupyter Notebook

To include a single tweet, pass the tweet’s ID from the tweet's URL as parameter to the shortcode:

{{< tweet 666616452582129664 >}}


## GitHub gist

{{< gist USERNAME GIST-ID  >}}


## $\rm \LaTeX$ math

Academic supports a Markdown extension for $\LaTeX$ math. You can enable this feature by toggling the math option in your config/_default/params.toml file and adding markup: mmark to your page front matter.

To render inline or block math, wrap your LaTeX math with $$...$$.

Example math block:

$$\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |} {\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$$


renders as

$\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$

Example inline math $$\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2$$ renders as $$\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2$$ .

Example multi-line math using the \\ math linebreak:

$$f(k;p_0^*) = \begin{cases} p_0^* & \text{if }k=1, \\ 1-p_0^* & \text {if }k=0.\end{cases}$$


renders as

$f(k;p_0^*) = \begin{cases} p_0^* & \text{if }k=1, \\ 1-p_0^* & \text {if }k=0.\end{cases}$

If markup: mmark is not placed in the front matter of all pages using math, then Markdown special characters need to be escaped in the math with a backslash to prevent the math being parsed as Markdown. For example, * and _ become \* and \_ respectively.

As Hugo and Academic attempt to parse YAML, Markdown, and LaTeX content in the abstract, the following guidelines should be followed just for the publication abstract and abstract_short fields:

• escape each LaTeX backslash (\) with an extra backslash, yielding \\
• escape each LaTeX underscore (_) with two backslashes, yielding \\_

Hence, abstract: "${O(d_{\max})}$" becomes abstract: "${O(d\\_{\\max})}$".

## Table

Code:

| Command           | Description                    |
| ------------------| ------------------------------ |
| hugo            | Build your website.            |
| hugo serve -w   | View your website.             |


Result:

CommandDescription
hugoBuild your website.
hugo serve -wView your website.

Academic supports a Markdown extension for asides, also referred to as alerts.

Asides are a useful feature that add side content such as notes, hints, or warnings to your articles. They are especially handy when writing educational tutorial-style articles or documentation.

You can enable this feature either by using the Alert shortcode below or by adding markup: mmark to your page front matter and prefixing a paragraph with A>. The paragraph will render as an aside with the default note style:

A> A Markdown aside is useful for displaying notices, hints, or definitions to your readers.


renders as

Alternatively, you can use the more powerful Alert shortcode which offers more options and does not require markup: mmark.

{{% alert note %}}
Here's a tip or note...


This will display the following note block:

Here’s a tip or note…
{{% alert warning %}}
Here's some important information...


This will display the following warning block:

Here’s some important information…

A table of contents may be particularly useful for long posts or tutorial/documentation type content. Use the {{% toc %}} shortcode anywhere you wish within your Markdown content to automatically generate a table of contents.
Note that this feature is not currently compatible with the markup: mmark front matter option.