hugo-tufte/README.md

Tufte Hugo Theme

History of this project

Hugo-Tufte is a minimalist blog-like theme for the static site generator Hugo that attempts to be a faithful implementation of the Tufte-css project. The current version supports mathematical typesetting via KaTeX.

• The original repo: shawnohare/hugo-tufte
• Second repo: slashformotion/hugo-tufte
• This (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:

    choco install hugo-extended # remember, you might need admin privs
    

• On macOS:
  • Using Homebrew:

    brew install hugo
    

Check out the example site

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

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.yaml to let your site know to actually use this theme, specifically.

Then run hugo server --buildDrafts --disableFastRender and open localhost:1313 or wherever it says in browser.

Features

Math

In this version, I use Yihui Xie's method to support (almost) seamless LaTeX rendering with KaTeX.

For usage and examples, refer to ./exampleSite/content/posts/tufte-features.md .

Downside: LaTeX in post title is no longer supported.

Site Parameters

params for this theme are:

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

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
• linkedin: string
• patreon: string
• youtube: string
• medium: string
• reddit: string
• stackoverflow: string
• instagram: string
• mastodon: string
• orcid: string
• google_scholar: string

Please see exampleSite/config.yaml to see the full implementation with exemples.

Page Parameters

• 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.
  • type string: If set to book, layout files in ./layouts/book/ will be prioritised.
  • layout string: If set, layout files with the name of this field's value will be prioritised.

Shortcodes

This theme provides the following shortcodes in an attempt to completely support all the features present in the Tufte-css project.

For usage and examples, refer to ./exampleSite/content/posts/tufte-features.md .

• blockquote
• div
• epigraph
• marginnote
• sidenote