From ebf3198ee3c5731da301a00206503f1c2b6407bc Mon Sep 17 00:00:00 2001 From: loikein Date: Mon, 24 Apr 2023 18:57:16 +0100 Subject: [PATCH] update readme --- README.md | 178 ++++++------------ exampleSite/config.yaml | 8 +- .../content/{post => posts}/blockquote.md | 0 .../content/{post => posts}/more-maths.md | 0 exampleSite/content/{post => posts}/new.md | 0 exampleSite/content/{post => posts}/nodate.md | 0 .../content/{post => posts}/tufte-css.md | 0 .../content/{post => posts}/tufte-features.md | 0 8 files changed, 61 insertions(+), 125 deletions(-) rename exampleSite/content/{post => posts}/blockquote.md (100%) rename exampleSite/content/{post => posts}/more-maths.md (100%) rename exampleSite/content/{post => posts}/new.md (100%) rename exampleSite/content/{post => posts}/nodate.md (100%) rename exampleSite/content/{post => posts}/tufte-css.md (100%) rename exampleSite/content/{post => posts}/tufte-features.md (100%) diff --git a/README.md b/README.md index 62e983f..64ab9db 100644 --- a/README.md +++ b/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 # create your new site with hugo in your pwd -cd \themes\ # cd into the themes directory -git clone # HTTPS link @ the top of the page if you've never done this before +```shell +hugo new site +cd /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 `

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

-\begin{aligned} - e &= (xy)^2 \\ - &=xyxy \implies \\ - y^{-1} &= xyx \implies \\ - y^{-1}x^{-1} &= xy, -\end{aligned} -

- -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 - `
` tag, while - `{{
}}` inserts the closing `
` 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 - `
` tag, while - `{{
}}` inserts the closing `
` tag. - - - `sidenote` - - **Description**: Wrap text to produce an automatically numbered sidenote. - - **Usage**: identical to `marginnote` - `{{< sidenote >}}...{{< /sidenote >}}` - - **Example**: - ```html - {{< sidenote >}}Some sidenote{{< /sidenote >}} - ``` - diff --git a/exampleSite/config.yaml b/exampleSite/config.yaml index 9a4440b..1aa0e35 100644 --- a/exampleSite/config.yaml +++ b/exampleSite/config.yaml @@ -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. diff --git a/exampleSite/content/post/blockquote.md b/exampleSite/content/posts/blockquote.md similarity index 100% rename from exampleSite/content/post/blockquote.md rename to exampleSite/content/posts/blockquote.md diff --git a/exampleSite/content/post/more-maths.md b/exampleSite/content/posts/more-maths.md similarity index 100% rename from exampleSite/content/post/more-maths.md rename to exampleSite/content/posts/more-maths.md diff --git a/exampleSite/content/post/new.md b/exampleSite/content/posts/new.md similarity index 100% rename from exampleSite/content/post/new.md rename to exampleSite/content/posts/new.md diff --git a/exampleSite/content/post/nodate.md b/exampleSite/content/posts/nodate.md similarity index 100% rename from exampleSite/content/post/nodate.md rename to exampleSite/content/posts/nodate.md diff --git a/exampleSite/content/post/tufte-css.md b/exampleSite/content/posts/tufte-css.md similarity index 100% rename from exampleSite/content/post/tufte-css.md rename to exampleSite/content/posts/tufte-css.md diff --git a/exampleSite/content/post/tufte-features.md b/exampleSite/content/posts/tufte-features.md similarity index 100% rename from exampleSite/content/post/tufte-features.md rename to exampleSite/content/posts/tufte-features.md