hugo-tufte/README.md

131 lines
5.2 KiB
Markdown
Raw Permalink Normal View History

2015-12-30 03:35:20 +01:00
# Tufte Hugo Theme
2023-04-15 17:20:36 +02:00
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](code_of_conduct.md) [![Test Build](https://github.com/loikein/hugo-tufte/actions/workflows/test-build.yml/badge.svg)](https://github.com/loikein/hugo-tufte/actions/workflows/test-build.yml) [![Netlify Status](https://api.netlify.com/api/v1/badges/0a3e11e2-0209-40bb-8570-c3eb9b8471dc/deploy-status)](https://app.netlify.com/sites/huto-tufte/deploys)
2022-02-18 11:07:43 +01:00
2023-04-24 19:57:16 +02:00
## History of this project
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
2023-04-24 19:57:16 +02:00
[Tufte-css](https://github.com/edwardtufte/tufte-css) project. The current version supports mathematical typesetting via [KaTeX](https://katex.org/).
2015-12-30 03:35:20 +01:00
2023-04-24 19:57:16 +02:00
- 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.
2021-01-31 23:51:55 +01:00
## Quickstart
### Prerequisite: Hugo Extended
You'll need to install Hugo Extended for this theme to test it locally, since this theme uses SCSS.
2023-04-24 19:57:16 +02:00
- On Windows:
- Using [Chocolatey](https://chocolatey.org/):
2023-04-24 19:57:16 +02:00
```shell
choco install hugo-extended # remember, you might need admin privs
```
2023-04-24 19:57:16 +02:00
- 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
2023-04-24 19:57:16 +02:00
```shell
hugo new site <your-site-name>
cd <your-site-name>/themes/
git clone https://github.com/loikein/hugo-tufte.git
```
2023-04-24 19:57:16 +02:00
Add `theme: 'hugo-tufte'` to your `config.yaml` to let your site know to actually use _this_ theme, specifically.
2023-04-24 19:57:16 +02:00
Then run `hugo server --buildDrafts --disableFastRender` and open `localhost:1313` or wherever it says in browser.
2021-07-25 10:05:22 +02:00
## Features
### Math
2023-04-24 19:57:16 +02:00
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/).
2023-04-29 06:42:29 +02:00
For usage and examples, refer to [./exampleSite/content/posts/tufte-features.md ](https://github.com/loikein/hugo-tufte/blob/main/exampleSite/content/posts/tufte-features.md).
2023-04-24 19:57:16 +02:00
Downside: LaTeX in post title is no longer supported.
2021-07-25 10:05:22 +02:00
### Site Parameters
2015-12-30 03:35:20 +01:00
2023-04-25 15:44:03 +02:00
`params` for this theme are:
2015-12-30 03:35:20 +01:00
2023-04-24 19:57:16 +02:00
- `subtitle` string: If set, displayed under the main title.
- `showPoweredBy` boolean: If `true`, display a shoutout to Hugo and this theme.
2015-12-30 03:35:20 +01:00
- `copyrightHolder` string: Inserts the value in the default copyright notice.
- `copyright` string: Custom copyright notice.
2021-07-30 21:19:04 +02:00
- `math` boolean: Site wide kill switch for Latex support
2023-04-24 19:57:16 +02:00
- `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.)
2023-07-03 16:06:55 +02:00
- `sansSubtitle` boolean: If `true`, all subtitles (`h2` \& `h3`) will use up-right and sans-serif font. (As seen in _Visual Display of Quantitative Information_.)
- (`centerArticle` boolean: Not implemented yet)
2015-12-30 03:35:20 +01:00
2023-04-24 19:57:16 +02:00
**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:
2023-04-24 19:57:16 +02:00
- `github`: string
- `gitlab`: string
- `twitter`: string
- `linkedin`: string
- `patreon`: string
- `youtube`: string
- `medium`: string
- `reddit`: string
- `stackoverflow`: string
- `instagram`: string
- `mastodon`: string
- `orcid`: string
- `google_scholar`: string
2023-04-24 19:57:16 +02:00
Please see [`exampleSite/config.yaml`](https://github.com/loikein/hugo-tufte/blob/main/exampleSite/config.yaml#L47) to see the full implementation with exemples.
2021-07-25 10:05:22 +02:00
### Page Parameters
2015-12-30 03:35:20 +01:00
2023-04-24 19:57:16 +02:00
- `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.
2015-12-30 03:35:20 +01:00
- `toc` boolean: if true, display the table of contents for the page.
2023-04-24 19:57:16 +02:00
- 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.
2023-04-25 15:44:03 +02:00
+ `layout` string: If set, layout files with the name of this field's value will be prioritised.
2015-12-30 03:35:20 +01:00
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
2023-04-24 19:57:16 +02:00
support all the features present in the [Tufte-css](https://github.com/edwardtufte/tufte-css) project.
2023-04-29 06:42:29 +02:00
For usage and examples, refer to [./exampleSite/content/posts/tufte-features.md ](https://github.com/loikein/hugo-tufte/blob/main/exampleSite/content/posts/tufte-features.md).
2023-04-24 19:57:16 +02:00
- `blockquote`
- `div`
- `epigraph`
- `marginnote`
- `sidenote`