Fork of Hugo "Tufte" theme
fix: more README link changes for the sr.ht move
change: updates readme for fork

heads

tip
browse log

clone

read-only
https://hg.sr.ht/~ser/hugo-tufte
read/write
ssh://hg@hg.sr.ht/~ser/hugo-tufte

#Tufte Hugo Theme

Test BuildLicense (MIT)

#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
  • Third repo: (loikein/hugo-tufte) is now the de facto third repo although my original intension was only to make a few tweaks.
  • This repo: (~ser/hugo-tufte). Moved from github to Sourcehut, and from git to Mercurial. The motivation was because Hugo keeps changing its API (by refusing to release a 1.x.x release, even on an 11 year-old project, they cleverly avoid committing to backwards compatability and keep their theme developers in instability hell! Genius!), and the theme needed updating in advance of breaking changes. The hosting move was because monocultures suck, and the VCS change was because Mercurial is objectively superior to to Git.

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

#Check out the example site

hg clone https://hg.sr.ht/~ser/hugo-tufte
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/
hg clone https://hg.sr.ht/~ser/hugo-tufte

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