update readme

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.
+[Tufte-css](https://github.com/edwardtufte/tufte-css) project. The current version supports mathematical typesetting via [KaTeX](https://katex.org/).
-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.
 
-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
+```shell
-# this code is shell-agnostic, and should work in cmd, powershell, bash, zsh....
+hugo new site <your-site-name>
-hugo new site <your-site-name> # create your new site with hugo in your pwd
+cd <your-site-name>/themes/
-cd <your-site-name>\themes\    # cd into the themes directory
+git clone https://github.com/loikein/hugo-tufte.git
-git clone <this-git-repo>      # HTTPS link @ the top of the page if you've never done this before
 ```
 
-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.
+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).
-- A simple displayed equation: `$$f(x, y) := e^{x^2 - y^2}.$$`
 
-There currently seems to be some weirdness with other environments,
+Downside: LaTeX in post title is no longer supported.
-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.
-```
 
 ### Site Parameters
 
 The site specific parameters that this theme recognizes are:
 
-- `subtitle` string: This is displayed under the main title.
+- `subtitle` string: If set, displayed under the main title.
-- `showPoweredBy` boolean: if true, display a shoutout to Hugo and this theme.
+- `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
+- `math` boolean: If `true`, try to render the page's LaTeX code using KaTeX.
-  true, `hideDate` takes greater precedence.
+- `meta` boolean: If `true`, display page metadata such as author, date, categories.
-- `hideReadTime` boolean: if true, do not display the page's reading time
+  + `hideDate` boolean: If `true`, do not display a page date in metadata.
-  estimate.  When `meta` is set to true, `hideReadTime` takes greater precedence.
+  + `hideReadTime` boolean: if `true`, do not display the page's reading time
-- `math` boolean: if true, try to render the page's LaTeX code using MatheJax.
+  estimate in metadata.
-- `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.
 - `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
+support all the features present in the [Tufte-css](https://github.com/edwardtufte/tufte-css) project.
-[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 >}}
-  ```
-

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.