From 0305f31cbca70631c656f64de7ee9b3d1bb9430e Mon Sep 17 00:00:00 2001 From: Spencer Brower <6729162+sbrow@users.noreply.github.com> Date: Wed, 12 Aug 2026 17:28:44 -0400 Subject: [PATCH] feat(site): Updated docs. --- TODOS.md | 1 + site/content/docs.md | 268 +++++++++++++++++++++++++++++++++++++------ site/content/faq.md | 68 +++++++++++ site/thor.json | 7 +- 4 files changed, 309 insertions(+), 35 deletions(-) create mode 100644 site/content/faq.md diff --git a/TODOS.md b/TODOS.md index 6a292ad..1b0480a 100644 --- a/TODOS.md +++ b/TODOS.md @@ -87,5 +87,6 @@ Debug log stats: - [ ] etc ## sbrow.github.io +- [ ] The home file was accidentally deleted in commit 9a9f731 - [ ] Ideas is now in the wrong spot. Date is wrong, and it is showing date when it shouldn't be. diff --git a/site/content/docs.md b/site/content/docs.md index 82f9611..3e9108d 100644 --- a/site/content/docs.md +++ b/site/content/docs.md @@ -3,6 +3,19 @@ "date": "2026-07-22T08:54:00-04:00", "toc": true } + ## Introduction @@ -10,13 +23,26 @@ This guide assumes you have either read [The Guide](../guide), or have built a [ ## Features -Thor has many features and content processors available. In an effort to provide the best out of the box experience, most of them are enabled by default. +Thor has many features and content processors available. In an effort to provide the best out of the box experience, most of them are enabled by default. Those that aren't are chosen because either: + +1. Significant Performance loses. +2. Unexpected behaviour (content mangling) + +If you feel that an extension is in the wrong category, let is know! [^issues] + +[^issues]: TODO: Add a link to issues from here. ### Opt-In Features -TODO: #### deflist syntax +#### Footnotes -TODO: #### footnotes +By default, Thor uses Tufte style margin notes instead of footnotes. However, if you prefer Hugo style footnotes, you can enable them in the [config](#configuration) file. + +TODO: Explain what tufte style is. + +#### Syntax Highlighting + +The highlight extension enables server-side syntax highlighting, powered by TreeSitter. This feature requires downloading a grammar file for each language you want to highlight, and will raise your build times from several milliseconds to over 250 #### Minify @@ -24,22 +50,28 @@ If enabled, `minify` will perform simple whitespace removal on all your output ` TODO: Do we minify inline css? +#### Sections + +The `sections` extension wraps each of your content sections in a `
` block. Sections are opened just before each heading, and closed before the next heading, or the end the document, whichever comes first. + ### Opt-Out Features - emoji - sidenotes/marginnotes - syntax highlighting - heading ids -- TODO: Table Of Contents Generation +- Table Of Contents Generation - [GitHub style alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) +- deflist syntax[^deflist] +[^deflist]: This may become opt-in in the future. ## Directories Like Hugo, a Thor project is a collection of specially named directories, plus an optional config file. All directories are optional, but it is recommended to at least have a `content` directory. content -: `content` holds your pages and page bundles. See [Content](#content). If not found, thor will look for content files in the root of your current working directory. +: `content` holds your pages and page bundles. If not found, thor will look for content files in the root of your current working directory. See [Content](#content) for more details. assets : `assets` contains any static files for your site (favicon.ico, etc.), as well as files you want to send through the asset pipeline (CSS or JS files). @@ -53,7 +85,7 @@ layouts All of these names can be remapped in `thor.json`.[^remap] -[^remap]: While directories can be remapped at the site level, modules must (currently) adhere to the defaults. +[^remap]: While directories can be remapped at the site level, [modules](#modules) must (currently) adhere to the defaults. ### Assets @@ -84,40 +116,83 @@ TODO: Don't forget to highlight differences from Hugo. ## Templates -Sites are built using one or more template files written in an extended version of [mustache](https://mustache.github.io) templates. The [mustache manual](https://mustache.github.io/mustache.5.html) has great explainations and a lot of examples if you want to know more, but I'll summarize them for you here. - -The beauty of Mustache is that there is very little syntax; there are just 10 symbols you need learn: `{{`, `{{&`, `{{^`, `{{>`, `{{<`, `{{#`, `/}}`, `{{$`, `{{!`, and `|`. - -TODO: ^^ Badly worded sentence ^^ +Sites are built using one or more template files written with an extended version of [mustache](https://mustache.github.io). The [mustache manual](https://mustache.github.io/mustache.5.html) has great explainations and a lot of examples, but this section should tell you everything you need to know. TODOS: Gotta describe base templates somewhere. (the same way we describe the partials) ### Tags +The beauty of Mustache is that there is very little syntax; there are just 10 symbols you need learn: `{{`, `{{&`, `{{^`, `{{>`, `{{<`, `{{#`, `/}}`, `{{$`, `{{!`, and `|`. + #### Variables -In order to display a scalar (not-list) value in your template, simply wrap it in double curly braces. e.g. `{{ page.title }}`. +In order to display a scalar (non-list) value in your template, simply wrap it in double curly braces. e.g. `{{ page.title }}`. -This content will be HTML escaped (for safety), so if the value you're rendering contains HTML, you'll need to use the raw syntex instead `{{& page.title}}`[^raw] which will output the value without stripping or re-writing content. +This content will be HTML escaped (for safety), so if the value you're rendering contains HTML, you'll need to use the raw syntax instead `{{& page.title}}`[^raw] which will output the value without escaping your HTML. Do so at your own risk.[^risk] -[^raw]: Official Triple brace syntax (`{{{ raw }}}`) is also supported, but `{{& raw }}` is preferred, as it's easy to accidentily insert too many braces. +[^risk]: Or don't, if you don't know why this is dangerous. + +[^raw]: Mustache also supports raw output through triple brace syntax (`{{{ raw }}}`), but `{{& raw }}` is preferred, as it's easy to accidentily insert too many braces. + +Leading and trailing whitespace(s) are ignored by the parser, so the folllowing are all equivilent: `{{& title }}`, `{{&title}}`, `{{& title}}`, `{{&title }}`. In most[^most] cases, invalid keys will be silently ignored (nothing between the braces will appear), in keeping with the official mustache spec. -[^most]: TODO: in what cases won't it? spelllcheck + strict mode? +[^most]: TODO: in what cases won't it? spelllcheck + strict mode? Also, people don't care about the spec, they care about how the app works. Also maybe mention strict mode here. -Leading and trailing whitespace(s) are ignored by the parser, so the folllowing are all equivilent: `{{& title }}`, `{{&title}}`, `{{& title}}`. #### Sections -TODO: +> Sections render blocks of text zero or more times, depending on the value of the key in the current context. + +Sections allow you to render text conditionally, and also allow you to render lists[^iffor]. They are opened with `{{#key}}` and closed with `{{/key}}`. + +[^iffor]: These would be your `if` and `for` blocks in a logic-ful language. + +```mustache +{{og.title}} +Shown if OpenGraph title is set! +{{/og.title}} + + +``` #### Inverted Sections -TODO: +All of the syntax we've described so far renders text when its value is *not* empty. Inverted sections render text when the value given to them *is* empty.[^unless] This allows you to display special conent when no values exist, for example. + +> [!NOTE] +> Empty values include `""` (an empty string), `[]` (an empty list), `false` + +Inverted sections are opened with `{{^key}}` and closed with `{{/key}}`. + +```mustache + +{{^pages}} +We don't have anything to show you right now, come back later! +{{/pages}} +``` + +[^unless]: This would be your `if not` or `unless` keyword in a logic-ful template. #### Partials -TODO: +Single file templates have limited functionality. Fortunately, mustache lets you break your documents up into multiple files through the use of partials. -TODO: Talk about MAX_CONTEXT_DEPTH (currently 16) and how it limits the total number of nested templates to 13. (3 for `[site, page, ctx]`) +To include a partial, you use the `{{>name}}` syntax, where `name` is the path to the partial, relative to the `{{layouts_dir}}/partials` of the module. For example, with the default theme, the `footer` template exists in `{{theme_dir}}/layouts/partials/footer.html`, so you'd include it by adding `{{>footer}}` to you template. + +See [Partials](#partials-2) for more information. + + ##### Dynamic Partials @@ -127,6 +202,8 @@ TODO: #### Parents TODO: +Parents can be used by theme developers to create complex templates with multiple content slots. + #### Summary `{{page.title}}` for normal values @@ -135,7 +212,7 @@ TODO: `{{#params.is_starred}}{{/params.is_starred}}` for conditional content. `{{^pages}}No pages yet!{{/pages}}` to draw content when the value is empty. -### Section Names +### Block Names When building your own templates, you are of course free to pick whatever names you choose for your partials and content slots. However, sticking to conventions helps create consistency in the ecosystem, and reduces friction when relying on built-in templates. @@ -211,20 +288,24 @@ TODO: Write `stylesheets` -: A list of paths to css files the users wants to include globally. These are rendered by the `{{> styles }}` partial, and can be omitted on sites that use custom templates. +: A list of paths to css files the users wants to include globally. These are rendered by the `{{> styles }}` partial. TODO: ^^ Bad sentence? ^^ +`scripts` + +: A list of `