jwebsite/syntax/divs-commands.md

<!--
reviewed: 18/4/20
-->

# Divs and Commands

\blurb{Style your content quickly and easily with custom divs, make everything reproducible and maintainable with commands.}

\lineskip

\toc

## Div blocks

In order to locally style your content, you can use `@@divname ... @@` which will wrap the content in a `<div class="divname"> ... </div>` block which you can then style as you wish in your CSS stylesheet.
For instance, you may want to highlight some content with a light yellow background:

```plaintext
Some text then
@@important
  Some important content
@@
```

and then, in your CSS, you could use

```css
.important {
  background-color: lemonchiffon;
  padding: 0.5em;
  margin-bottom: 1em;
}
```

which will look like

@@important
  Some important content
@@

### Nesting

Such div blocks can be nested as in standard HTML.
The distinction with inserting raw HTML div blocks with the `~~~...~~~` syntax is that the content  of div blocks is processed as well (i.e.: can contain Franklin markdown):

```plaintext
@@important
  Some text;
  @@silly-formatting
    some **silly** text with $2x+4=y$.
  @@
  and more text.
@@
```

@@important
  Some text;
  @@silly-formatting
    some **silly** text with $2x+4=y$.
  @@
  and more text.
@@

## LaTeX-like commands

Franklin allows the definition of commands using a LaTeX-like syntax.
This can be particularly useful for repeating elements or styling inside or outside of maths environment.

To define a command, you **must** use the following syntax:

```plaintext
\newcommand{\name}[...]{...}
             -1-   -2-  -3-
```

where:

@@flist
1. the first bracket is the _command name_, starting with a backslash and _only made out of letters_ (lower or upper case),
1. the second (optional) bracket indicates the _number of arguments_, if none is set the command does not take arguments,
1. the third bracket indicates the _definition of the command_ calling `#k` to insert the $k$-th argument.
@@

As in LaTeX, command definitions can be anywhere as long as they appear before they are used.
If you want a command to be available on all your pages, put the definition in the `config.md` file.

\note{Franklin currently cannot just take the content of a `.tex` document and convert it, this may be (partially) supported in the future if it is deemed useful. Mainly it would require pre-defining all standard commands such as `\textbf`, `\section`, etc.}

### Math examples

If you end up writing a lot of equations on your site, defining commands can become rather useful:

```plaintext
\newcommand{\R}{\mathbb R}

Let $f:\R\to\R$ a function...
```

\newcommand{\R}{\mathbb R}
Let $f:\R\to\R$ a function...

```plaintext
\newcommand{\scal}[1]{\left\langle #1 \right\rangle}

$$ \mathcal W_\psi[f] = \int_\R f(s)\psi(s)\mathrm{d}s = \scal{f,\psi} $$
```

\newcommand{\scal}[1]{\left\langle #1 \right\rangle}
$$ \mathcal W_\psi[f] = \int_\R f(s)\psi(s)\mathrm{d}s = \scal{f,\psi} $$

### Text examples

Commands can also be useful outside of maths environment.
For instance, you could define a command to quickly set the style of some text:

```html
\newcommand{\styletext}[2]{~~~<span style="#1">#2</span>~~~}

Here is \styletext{color:magenta;font-size:14px;}{formatted text}.
```

\newcommand{\styletext}[2]{~~~<span style="#1">#2</span>~~~}

Here is \styletext{color:magenta;font-size:14px;font-variant:small-caps;}{formatted text}.

### Nesting examples

Commands are resolved recursively which means that they can be nested and their definition can contain further Franklin markdown (again this is similar to how LaTeX works).

Consider for instance:

```plaintext
\newcommand{\norm}[2]{\left\|#1\right\|_{#2}}
\newcommand{\anorm}[1]{\norm{#1}{1}}
\newcommand{\bnorm}[1]{\norm{#1}{2}}

Let $x\in\R^n$, there exists $0 < C_1 \le C_2$ such that

$$ C_1 \anorm{x} \le \bnorm{x} \le C_2\anorm{x}. $$
```

\newcommand{\norm}[2]{\left\|#1\right\|_{#2}} <!--_-->
\newcommand{\anorm}[1]{\norm{#1}{1}}
\newcommand{\bnorm}[1]{\norm{#1}{2}}

Let $x\in\R^n$, there exists $0 < C_1 \le C_2$ such that

$$ C_1 \anorm{x} \le \bnorm{x} \le C_2\anorm{x}. $$

As indicated earlier, commands can contain further Franklin markdown that is processed recursively.
For example, here is a more sophisticated example of a "definition" command such that this:

```plaintext
\definition{angle between vectors}{
  Let $x, y \in \R^n$ and let $\scal{\cdot, \cdot}$ denote
  the usual inner product. Then, the angle $\theta$ between
  $x$ and $y$ is given by
  $$ \cos(\theta) = {\scal{x,y}\over \scal{x,x} \scal{y,y}}. $$
}
```

leads to this:

\newcommand{\definition}[2]{@@definition **Definition**: (_!#1_) #2 @@}

\definition{angle between vectors}{
  Let $x, y \in \R^n$ and let $\scal{\cdot, \cdot}$ denote
  the usual inner product. Then, the angle $\theta$ between $x$ and $y$ is
  given by $$ \cos(\theta) = {\scal{x,y}\over \scal{x,x} \scal{y,y}}. $$
}

To do this, you would define the command:

```html
\newcommand{\definition}[2]{
  @@definition
  **Definition**: (_!#1_)
  #2
  @@
}
```

and specify the styling of the `definition` div in your CSS:

```css
.definition {
  background-color: aliceblue;
  border-left: 5px solid cornflowerblue;
  border-radius: 10px;
  padding: 10px;
  margin-bottom: 1em;
}
```

### Whitespaces

In a Franklin `newcommand`, to refer to an argument you can use `#k` or `!#k`.
There is a small difference: the first one _introduces a space_ left of the argument while the second one does not.

In general whitespaces are irrelevant and will not show up on the rendered webpage so that the usual `#k` is the recommended usage.
This helps avoid some ambiguities when resolving a chain of nested commands.

There are however cases where you do not want this because the whitespace does, in fact, show up.
In such cases use `!#k` (assuming it's not ambiguous).

Consider for instance:

```plaintext
\newcommand{\pathwith}[1]{`/usr/local/bin/#1`}
\newcommand{\pathwithout}[1]{`/usr/local/bin/!#1`}

Here \pathwith{hello} is no good whereas \pathwithout{hello} is.
```

\newcommand{\pathwith}[1]{`/usr/local/bin/#1`}
\newcommand{\pathwithout}[1]{`/usr/local/bin/!#1`}

Here \pathwith{hello} is no good whereas \pathwithout{hello} is.

### Defining commands globally

If you define commands on a page, the command will be available only on that page; if you wish to define a command that is available on all pages, you should  put the definition of the command in your `config.md` file.

## Hyper-references

Three types of hyper-references are supported in Franklin:

@@flist
1. for equations in display mode,
1. for references (bibliography),
1. for specific anchor points in the page.
@@

The syntax for all three is close to that of standard LaTeX.

To style the appearance of the maths or bib links in CSS, use `.franklin-content.eqref a` and `.franklin-content.bibref a` classes; for instance:

```css
.franklin-content .eqref a  {color: blue;}
.franklin-content .bibref a {color: green;}
```

### Equations

To label an equation, just use `\label{some label}` in the math environment and, to refer to it, use `\eqref{some label}`:

```plaintext
Some equation:

$$\exp(i\pi) + 1 = 0 \label{a cool equation}$$

and you can refer to it in the text: equation \eqref{a cool equation}.
```

As in LaTeX, you can refer to several equations in one shot by separating names with commas: `\eqref{some label, some other}` (that also means you cannot use commas in labels).

### References

For references, you can use `\biblabel{short}{name}` to declare a reference which will appear as a clickable link `(name)` or `name` and can be referred to with `short`:

```plaintext
In the text you may refer to \citep{noether15, bezanson17} while in a bibliography section you would have

* \biblabel{noether15}{Noether (1915)} **Noether**, Korper und Systeme rationaler Funktionen, 1915.
* \biblabel{bezanson17}{Bezanson et al. (2017)} **Bezanson**, **Edelman**, **Karpinski** and **Shah**, [Julia: a fresh approach to numerical computing](https://julialang.org/publications/julia-fresh-approach-BEKS.pdf), SIAM review 2017.
```

The `name` argument therefore corresponds to how the bibliography reference will appear in the text.
In the case above, the text will lead to

```plaintext
... refer to (Noether (1915), Bezanson et al. (2017)) while ...
```

You can use either

@@tlist
* `\cite{short1, short2}` or `\citet{short3}`: which will not add parentheses around the link(s),
* `\citep{short4, short5}`: which will add parentheses around the link(s).
@@

As in LaTeX, if the reference is undefined on the page, the command will be replaced by **(??)**.

### Anchor points

You can specify anchor points on the page using `\label{name of the anchor}` anywhere on the page _outside_ of maths environment.
This will insert an anchor:

```html
<a id="name-of-the-anchor"></a>
```

You can subsequently link to it on the same page:

```plaintext
[link to it](#name-of-the-anchor)
```

or from another page by prepending it with the path to the page, for instance:

```plaintext
[link to it](/index.html#name-of-the-anchor)
```

Note also that all section headers are anchor points for instance

```plaintext
### Some subtitle
```

can be linked to with `#some-subtitle`.
If there are multiple headers with the same name, the second and subsequent ones can be referred to with `#some-subtitle__2`, `#some-subtitle__3` etc. (note the double underscore).