TastyPancakes
/
jwebsite
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
jwebsite/syntax/divs-commands.md

9.2 KiB
Raw Blame History

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:

Some text then
@@important
  Some important content
@@

and then, in your CSS, you could use

.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):

@@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:

\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),
  2. the second (optional) bracket indicates the number of arguments, if none is set the command does not take arguments,
  3. 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:

\newcommand{\R}{\mathbb R}

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

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

\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:

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

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

\newcommand{\styletext}[2]{#2}

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:

\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:

\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:

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

and specify the styling of the definition div in your 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:

\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,
  2. for references (bibliography),
  3. 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:

.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}:

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:

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

... 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:

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

You can subsequently link to it on the same page:

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

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

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

Note also that all section headers are anchor points for instance

### 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).