hugo-tufte/README.md

141 lines
5.1 KiB
Markdown
Raw Normal View History

2015-12-30 03:35:20 +01:00
# Tufte Hugo Theme
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](code_of_conduct.md)
2021-01-31 23:51:55 +01:00
2015-12-30 03:35:20 +01:00
Hugo-Tufte is a minimalist blog-like theme for the
[static site generator Hugo](https://gohugo.io) that
attempts to be a faithful implementation of the
2017-06-23 18:55:52 +02:00
[Tufte-css](https://github.com/edwardtufte/tufte-css) project.
2021-07-21 20:23:55 +02:00
It supports mathematical typesetting via [katex](https://katex.org/).
2015-12-30 03:35:20 +01:00
By utilizing copious partial templates the theme is largely customizable.
2021-01-31 23:51:55 +01:00
## State of Project
2021-07-25 10:05:22 +02:00
This is a fork of the original [hugo-tufte](https://github.com/shawnohare/hugo-tufte).
2021-01-31 23:51:55 +01:00
2021-07-25 10:05:22 +02:00
## Features
### Math
2021-07-21 20:23:55 +02:00
[katex](https://katex.org/) renders LaTeX written inside of markdown files. LaTeX can be
written more or less as normal. Some examples:
2021-07-21 20:23:55 +02:00
- This `\\( \frac{1}{2} \\)` will be rendered inline.
- A simple displayed equation: `$$f(x, y) := e^{x^2 - y^2}.$$`
There currently seems to be some weirdness with other environments,
2021-07-25 10:05:22 +02:00
such as the `aligned` environment (`align*` is not supported by katex). These environments will render provided
they are wrapped in `<p>` tags and blank lines. The snippet below should
render correctly.
```
Let $G$ be a finite group with exponent $2$. Then every element is
an involution, hence for any $x$, $y$ in $G$ we have:
<p>
\begin{align*}
e &= (xy)^2 \\
&=xyxy \implies \\
y^{-1} &= xyx \implies \\
y^{-1}x^{-1} &= xy,
\end{align*}
</p>
establishing that $G$ is abelian.
```
2021-07-25 10:05:22 +02:00
### Site Parameters
2015-12-30 03:35:20 +01:00
2016-02-20 21:21:01 +01:00
The site specific parameters that this theme recognizes are:
2015-12-30 03:35:20 +01:00
- `subtitle` string: This is displayed under the main title.
- `showPoweredBy` boolean: if true, display a shoutout to Hugo and this theme.
- `copyrightHolder` string: Inserts the value in the default copyright notice.
- `copyright` string: Custom copyright notice.
2021-07-25 10:05:22 +02:00
### Page Parameters
2015-12-30 03:35:20 +01:00
- `hideDate` boolean: if true, do not display a page date. When `meta` is set to
true, `hideDate` takes greater precedence.
- `hideReadTime` boolean: if true, do not display the page's reading time
estimate. When `meta` is set to true, `hideReadTime` takes greater precedence.
- `math` boolean: if true, try to render the page's LaTeX code using MatheJax.
2016-02-21 18:56:21 +01:00
- `meta` boolean: if true, display page metadata such as author, date, categories provided
2015-12-30 03:35:20 +01:00
these page parameters exist and are not overridden. Content in the `/post` directory,
(i.e., pages of type "post") ignore this parameter.
- `toc` boolean: if true, display the table of contents for the page.
2021-07-25 10:05:22 +02:00
### Shortcodes
2016-02-20 21:21:01 +01:00
This theme provides the following shortcodes in an attempt to completely
support all the features present in the
2016-02-20 21:21:01 +01:00
[Tufte-css](https://github.com/edwardtufte/tufte-css) project.
2015-12-31 07:10:37 +01:00
- `blockquote`
2016-01-01 23:56:52 +01:00
- **Description**: Wrap text in a blockquote and insert optional
2015-12-31 07:10:37 +01:00
`cite` or `footer` metadata.
2016-01-01 23:56:52 +01:00
- **Usage**: Accepts the named parameters `cite` and `footer`.
- **Example**:
2015-12-31 07:10:37 +01:00
```html
2021-07-21 20:23:55 +02:00
{{< blockquote cite="www.shawnohare.com" footer="Shawn" >}}
There is nothing more beautiful than an elegant mathematical proof.
2021-07-21 20:23:55 +02:00
{{< /blockquote >}}
2015-12-31 07:10:37 +01:00
```
- `div`
2016-01-01 23:56:52 +01:00
- **Description**: This shortcode is provided as a work-around for wrapping
complex blocks of markdown in div tags. The wrapped text can
include other shortcodes
2016-01-01 23:56:52 +01:00
- **Usage**: Identical to the `section` shortcode.
Accepts the style parameters `class` and `id`.
2016-02-21 18:56:21 +01:00
If only the positional argument `"end"` is passed, a closing tag
will be inserted.
- **Example**: `{{< div class="my-class" >}}` inserts a
`<div class="my-class">` tag, while
`{{<div "end" >}}` inserts the closing `</div>` tag.
- `epigraph`
2016-01-01 23:56:52 +01:00
- **Description**: Create an epigraph with the wrapped text.
- **Usage**: To include a footer with source attribution, pass in the
optional named parameters `pre`, `cite`, `post`. These parameters
make no styling assumptions, so spacing is important. A more compactly
styled epigraph will be used if the `type` parameter is set to `compact`.
2016-01-01 23:56:52 +01:00
- **Example**:
2021-07-25 10:05:22 +02:00
```html
2021-07-21 20:23:55 +02:00
{{< epigraph pre="Author Writer, " cite="Math is Fun" >}}
This is an example of an epigraph with some math
2016-01-01 20:56:14 +01:00
\\( \mathbb N \subseteq \mathbb R \\)
to start the beginning of a section.
2021-07-21 20:23:55 +02:00
{{< /epigraph >}}
```
- `marginnote`
2016-01-01 23:56:52 +01:00
- **Description**: Wrap text to produce a numberless margin note.
2021-07-21 20:23:55 +02:00
- Usage: `{{< marginnote >}}...{{< /marginnote >}}`
- **Example**:
```html
{{< marginnote >}}Some marginnote{{< /marginnote>}}
```
- `section`
2016-01-01 23:56:52 +01:00
- **Description**: This shortcode is provided as a work-around for wrapping
complex blocks of markdown in section tags. The wrapped text can
include other shortcodes
2016-01-01 23:56:52 +01:00
- **Usage**: Accepts the style parameters `class` and `id`.
2016-02-21 18:56:21 +01:00
If only the positional argument `"end"` is passed, a closing tag
will be inserted.
- **Example**: `{{< section class="my-class" >}}` inserts a
`<section class="my-class">` tag, while
`{{<section "end" >}}` inserts the closing `</section>` tag.
- `sidenote`
2016-01-01 23:56:52 +01:00
- **Description**: Wrap text to produce an automatically numbered sidenote.
- **Usage**: identical to `marginnote`
2021-07-21 20:23:55 +02:00
`{{< sidenote >}}...{{< /sidenote >}}`
- **Example**:
```html
{{< sidenote >}}Some sidenote{{< /sidenote >}}
```