mirror of
https://github.com/loikein/hugo-tufte.git
synced 2024-11-14 20:36:58 +01:00
update readme
This commit is contained in:
parent
9e249d6e0c
commit
ebf3198ee3
8 changed files with 61 additions and 125 deletions
178
README.md
178
README.md
|
@ -1,94 +1,90 @@
|
|||
# Tufte Hugo Theme
|
||||
|
||||
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](code_of_conduct.md)
|
||||
[![build github pages](https://github.com/slashformotion/hugo-tufte/actions/workflows/build-site-ghpages.yml/badge.svg)](https://github.com/slashformotion/hugo-tufte/actions/workflows/build-site-ghpages.yml)
|
||||
|
||||
## Fork notes by loikein:
|
||||
|
||||
I just do whatever I want to make the theme better suit my needs. Not intended as a continuation of the original projects.
|
||||
|
||||
## Original readme:
|
||||
|
||||
***This theme isn't actively maintained, if you want a new feature please file a pull request.***
|
||||
|
||||
## History of this project
|
||||
|
||||
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
|
||||
[Tufte-css](https://github.com/edwardtufte/tufte-css) project.
|
||||
It supports mathematical typesetting via [katex](https://katex.org/) or [MathJax](https://www.mathjax.org).
|
||||
By utilizing copious partial templates the theme is largely customizable.
|
||||
[Tufte-css](https://github.com/edwardtufte/tufte-css) project. The current version supports mathematical typesetting via [KaTeX](https://katex.org/).
|
||||
|
||||
This is a fork of the original [hugo-tufte](https://github.com/shawnohare/hugo-tufte).
|
||||
- The original repo: [shawnohare/hugo-tufte](https://github.com/shawnohare/hugo-tufte)
|
||||
- Second repo: [slashformotion/hugo-tufte](https://github.com/slashformotion/hugo-tufte)
|
||||
- This ([loikein/hugo-tufte](https://github.com/loikein/hugo-tufte)) is now the _de facto_ third repo although my original intension was only to make a few tweaks.
|
||||
|
||||
## Quickstart
|
||||
|
||||
### Prerequisite: Hugo Extended
|
||||
|
||||
You'll need to install Hugo Extended for this theme to test it locally, since this theme uses SCSS.
|
||||
|
||||
- On Windows:
|
||||
- Using [Chocolatey](https://chocolatey.org/):
|
||||
```powershell
|
||||
```shell
|
||||
choco install hugo-extended # remember, you might need admin privs
|
||||
```
|
||||
- On macOS:
|
||||
+ Using [Homebrew](https://brew.sh/):
|
||||
```shell
|
||||
brew install hugo
|
||||
```
|
||||
|
||||
### Check out the example site
|
||||
|
||||
```shell
|
||||
git clone https://github.com/loikein/hugo-tufte.git
|
||||
cd hugo-tufte/exampleSite
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
Then open `localhost:1313` or wherever it says in browser.
|
||||
|
||||
The showcase posts are:
|
||||
|
||||
- `The big old test page`
|
||||
- `Tufte CSS`
|
||||
|
||||
### For a new site
|
||||
|
||||
```powershell
|
||||
# this code is shell-agnostic, and should work in cmd, powershell, bash, zsh....
|
||||
hugo new site <your-site-name> # create your new site with hugo in your pwd
|
||||
cd <your-site-name>\themes\ # cd into the themes directory
|
||||
git clone <this-git-repo> # HTTPS link @ the top of the page if you've never done this before
|
||||
```shell
|
||||
hugo new site <your-site-name>
|
||||
cd <your-site-name>/themes/
|
||||
git clone https://github.com/loikein/hugo-tufte.git
|
||||
```
|
||||
|
||||
Add `theme = 'hugo-tufte'` to your `config.toml` to let your site know to actually use _this_ theme, specifically.
|
||||
Add `theme: 'hugo-tufte'` to your `config.yaml` to let your site know to actually use _this_ theme, specifically.
|
||||
|
||||
Then run `hugo server -D` and open up `localhost:1313/` or wherever it says in Firefox.
|
||||
Then run `hugo server --buildDrafts --disableFastRender` and open `localhost:1313` or wherever it says in browser.
|
||||
|
||||
## Features
|
||||
|
||||
### Math
|
||||
|
||||
[Katex](https://katex.org/) or [MathJax](https://www.mathjax.org) renders LaTeX written inside of markdown files. LaTeX can be written more or less as normal. Some examples:
|
||||
In this version, I use [Yihui Xie's method](https://yihui.org/en/2018/07/latex-math-markdown/) to support (almost) seamless LaTeX rendering with [KaTeX](https://katex.org/).
|
||||
|
||||
- This `$\frac{1}{2}$` will be rendered inline.
|
||||
- A simple displayed equation: `$$f(x, y) := e^{x^2 - y^2}.$$`
|
||||
For usage and examples, refer to [./exampleSite/content/post/tufte-features.md ](https://github.com/loikein/hugo-tufte/blob/main/exampleSite/content/post/tufte-features.md).
|
||||
|
||||
There currently seems to be some weirdness with other environments,
|
||||
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.
|
||||
```latex
|
||||
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{aligned}
|
||||
e &= (xy)^2 \\
|
||||
&=xyxy \implies \\
|
||||
y^{-1} &= xyx \implies \\
|
||||
y^{-1}x^{-1} &= xy,
|
||||
\end{aligned}
|
||||
</p>
|
||||
|
||||
establishing that $G$ is abelian.
|
||||
```
|
||||
Downside: LaTeX in post title is no longer supported.
|
||||
|
||||
### Site Parameters
|
||||
|
||||
The site specific parameters that this theme recognizes are:
|
||||
|
||||
- `subtitle` string: This is displayed under the main title.
|
||||
- `showPoweredBy` boolean: if true, display a shoutout to Hugo and this theme.
|
||||
- `subtitle` string: If set, 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.
|
||||
- `math` boolean: Site wide kill switch for Latex support
|
||||
- `katex` boolean: if "katex" is set to true katex will be used to render LaTex, if not MathJax will be used instead. (Set to `true` by default)
|
||||
- `codeBlocksDark` boolean: if true, code blocks will use a dark theme.
|
||||
- `codeBlocksDark` boolean: If `true`, code blocks will use a dark theme.
|
||||
- `marginNoteInd` string: (NEW) Custom indicator for margin notes, with suggestions in comment. (Only displayed on mobile devices or inside `cols` shortcode.)
|
||||
|
||||
***Socials***
|
||||
**Socials**
|
||||
|
||||
_(The followings have not been tested for this repo, use at your own risk.)_
|
||||
|
||||
You can add links to your social media profile by using thoses parameters:
|
||||
|
||||
- `github`: string
|
||||
- `gitlab`: string
|
||||
- `twitter`: string
|
||||
|
@ -102,90 +98,30 @@ You can add links to your social media profile by using thoses parameters:
|
|||
- `orcid`: string
|
||||
- `google_scholar`: string
|
||||
|
||||
Please see [`exampleSite/config.toml`](https://github.com/slashformotion/hugo-tufte/blob/master/exampleSite/config.toml#L30) to see the full implementation with exemples.
|
||||
Please see [`exampleSite/config.yaml`](https://github.com/loikein/hugo-tufte/blob/main/exampleSite/config.yaml#L47) to see the full implementation with exemples.
|
||||
|
||||
### Page Parameters
|
||||
|
||||
- `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.
|
||||
- `meta` boolean: if true, display page metadata such as author, date, categories provided
|
||||
these page parameters exist and are not overridden. Content in the `/post` directory,
|
||||
(i.e., pages of type "post") ignore this parameter.
|
||||
- `math` boolean: If `true`, try to render the page's LaTeX code using KaTeX.
|
||||
- `meta` boolean: If `true`, display page metadata such as author, date, categories.
|
||||
+ `hideDate` boolean: If `true`, do not display a page date in metadata.
|
||||
+ `hideReadTime` boolean: if `true`, do not display the page's reading time
|
||||
estimate in metadata.
|
||||
- `toc` boolean: if true, display the table of contents for the page.
|
||||
- Layout parameters: (NEW)
|
||||
+ For more information, see [Hugo's Lookup Order | Hugo](https://gohugo.io/templates/lookup-order/).
|
||||
+ `type` string: If set to `book`, layout files in [./layouts/book/](https://github.com/loikein/hugo-tufte/tree/main/layouts/book) will be prioritised.
|
||||
+ `layout` string: If set, layout files with this same will be prioritised.
|
||||
|
||||
### Shortcodes
|
||||
|
||||
This theme provides the following shortcodes in an attempt to completely
|
||||
support all the features present in the
|
||||
[Tufte-css](https://github.com/edwardtufte/tufte-css) project.
|
||||
support all the features present in the [Tufte-css](https://github.com/edwardtufte/tufte-css) project.
|
||||
|
||||
For usage and examples, refer to [./exampleSite/content/post/tufte-features.md ](https://github.com/loikein/hugo-tufte/blob/main/exampleSite/content/post/tufte-features.md).
|
||||
|
||||
- `blockquote`
|
||||
- **Description**: Wrap text in a blockquote and insert optional
|
||||
`cite` or `footer` metadata.
|
||||
- **Usage**: Accepts the named parameters `cite` and `footer`.
|
||||
- **Example**:
|
||||
```html
|
||||
{{< blockquote cite="www.shawnohare.com" footer="Shawn" >}}
|
||||
There is nothing more beautiful than an elegant mathematical proof.
|
||||
{{< /blockquote >}}
|
||||
```
|
||||
|
||||
- `div`
|
||||
- **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
|
||||
- **Usage**: Identical to the `section` shortcode.
|
||||
Accepts the style parameters `class` and `id`.
|
||||
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`
|
||||
- **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`, `link`. 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`.
|
||||
- **Example**:
|
||||
```html
|
||||
{{< epigraph pre="Author Writer, " cite="Math is Fun" link='https://www.google.com' >}}
|
||||
This is an example of an epigraph with some math
|
||||
$ \mathbb N \subseteq \mathbb R $
|
||||
to start the beginning of a section.
|
||||
{{< /epigraph >}}
|
||||
```
|
||||
|
||||
- `marginnote`
|
||||
- **Description**: Wrap text to produce a numberless margin note.
|
||||
- Usage: `{{< marginnote >}}...{{< /marginnote >}}`
|
||||
- **Example**:
|
||||
```html
|
||||
{{< marginnote >}}Some marginnote{{< /marginnote>}}
|
||||
```
|
||||
|
||||
- `section`
|
||||
- **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
|
||||
- **Usage**: Accepts the style parameters `class` and `id`.
|
||||
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`
|
||||
- **Description**: Wrap text to produce an automatically numbered sidenote.
|
||||
- **Usage**: identical to `marginnote`
|
||||
`{{< sidenote >}}...{{< /sidenote >}}`
|
||||
- **Example**:
|
||||
```html
|
||||
{{< sidenote >}}Some sidenote{{< /sidenote >}}
|
||||
```
|
||||
|
||||
|
|
|
@ -77,19 +77,19 @@ menu:
|
|||
- name: Posts
|
||||
weight: -100
|
||||
identifier: posts
|
||||
url: /posts
|
||||
url: /posts/
|
||||
- name: Categories
|
||||
weight: -90
|
||||
identifier: categories
|
||||
url: /categories
|
||||
url: /categories/
|
||||
- name: About
|
||||
weight: -80
|
||||
identifier: about
|
||||
url: /about
|
||||
url: /about/
|
||||
- name: Source Code
|
||||
weight: -70
|
||||
identifier: github
|
||||
url: "https://github.com/slashformotion/hugo-tufte"
|
||||
url: "https://github.com/loikein/hugo-tufte"
|
||||
# -----------------------------------------------------------------------
|
||||
# FOOTER MENU
|
||||
# If you need to add custom links to you footer: put them here.
|
||||
|
|
Loading…
Reference in a new issue