✏️ Fix docs and contributing typos (#4)

* ✨ Added some missing features to the default theme

* ✏️ Fixed docs and contributing typos

* 🚧 Attempted to add examples

* 🚧 Gave up on the examples

* 📝 Finished the docs overhaul

* 📝 Made the headings easier to differentiate

* 📝 Improved the documentation for the create-entry functions

* 📝 Rerendered the docs

* 📝 Fixed formatting of raw blocks

---------

Co-authored-by: BattleCh1cken <BattleCh1cken@larkov.de>

Author: Isaiah15414

.github/CONTRIBUTING.md

@@ -22,7 +22,7 @@ All types of contributions are encouraged and valued. See the [Table of Contents
 - [Suggesting Enhancements](#suggesting-enhancements)
 - [Your First Code Contribution](#your-first-code-contribution)
 - [Improving The Documentation](#improving-the-documentation)
-- [Styleguides](#style-guides)
+- [Style Guides](#style-guides)
 - [Typst Code](#typst-code)
 - [Commit Messages](#commit-messages)
 

docs-template.typ

@@ -16,10 +16,34 @@
   set page(numbering: "1", number-align: center)
   set text(font: "Linux Libertine", lang: "en")
 
-  show heading.where(level: 1): it => block(smallcaps(it), below: 1em)
+  show heading: it => {
+    if it.level == 1 {
+      set align(left)
+      set text(20pt)
+      box(it)
+      box(line(length: 100%))
+    } else if it.level == 2 {
+      set text(18pt)
+      it
+    } else if it.level == 3 {
+      set text(15pt)
+      it
+    } else if it.level == 4 {
+      set text(14pt)
+      it
+    } else if it.level == 5 {
+      set text(12pt)
+      it.body
+    } else if it.level == 6 {
+      set text(12pt)
+      it.body
+    } else {
+      panic("invalid heading level")
+    }
+  }
+
   set heading(numbering: "1.")
 
-  // show link: set text(fill: purple.darken(30%))
   show link: set text(fill: rgb("#1e8f6f"))
   show link: underline
 
@@ -62,13 +86,15 @@
   v(10em)
 
   show: codly-init
-  codly()
+  codly(enable-numbers: false)
+
   show raw.where(block: true): set text(size: .95em)
   show raw.where(block: true): it => pad(x: 4%, it)
 
+  //FIXME: make this work again
   show raw.where(block: false): it => if it.text.starts-with("<") and it.text.ends-with(">") {
     set text(1.2em)
-    tidy.styles.default.show-type(it.text.slice(1, -1))
+    tidy.styles.default.show-type(it.text.slice(1, -1), style-args: tidy.styles.default)
   } else {
     it
   }

docs.pdf

@@ -1,27 +1,36 @@
 #import "./docs-template.typ": *
-#import "./packages.typ": tidy
-
+#import "./packages.typ": tidy, gentle-clues
+#import gentle-clues: *
 
 #let version = toml("/typst.toml").package.version
 #let import-statement = "#import \"@preview/tidy:" + version + "\""
 
 #show: docs-template.with(
-  title: "The Notebookinator", subtitle: "Easy formatting for robotics notebooks.", abstract: [
-    Welcome to the Notebookinator, a Typst package meant to simply the notebooking
+  title: "The Notebookinator",
+  subtitle: "Easy formatting for robotics notebooks.",
+  abstract: [
+    Welcome to the Notebookinator, a Typst package meant to simplify the notebooking
     process for the Vex Robotics Competition. Its theming capabilities handle all of
     the styling for you, letting you jump right into writing documentation.
 
     While it was designed with VRC in mind, it could just as easily be used for
     other competitor systems such as the First Robotics Competition and the First
     Tech Challenge.
-  ], version: version, url: "https://github.com/BattleCh1cken/notebookinator",
+  ],
+  version: version,
+  url: "https://github.com/BattleCh1cken/notebookinator",
 )
 
 #outline(indent: true, depth: 3)
 #pagebreak(weak: true)
 
 = Installation
 
+#info[
+  This installation process is temporary, as we wait for Typst to overhaul its
+  process for packaging templates and packages.
+]
+
 The best way to install the Notebookinator is as a local package. Make sure you
 have the following software installed on your computer:
 
@@ -38,28 +47,35 @@ cd notebookinator
 just install
 ```
 
+#info[
+  If you're running this on Windows, you'll need to run these commands in a sh
+  shell, like git-bash or the shell packaged with Cygwin or GitHub Desktop.
+]
+
 = Basic Usage
 
 Once the template is installed, you can import it into your project like this:
 
 #raw(
   block: true,
   lang: "typ",
-  "#import \"@local/notebookinator:"+ version + "\": *"
+  "#import \"@local/notebookinator:" + version + "\": *",
 )
 
 Once you've done that you can begin to write your notebook:
+
 ```typ
 #import themes.default: default-theme, components
 
 #show: notebook.with(theme: default-theme)
 
 #create-body-entry(title: "My Entry")[
-  #lorem(200)
+ #lorem(200)
 ]
 ```
 
 You can then compile your notebook with the Typst CLI:
+
 ```bash
 typst compile your-notebook-file.typ
 ```
@@ -88,20 +104,35 @@ typst compile your-notebook-file.typ
 Themes are stored as dictionaries with a set number of fields.
 
 #def-arg(
-  "rules", [`<function>`], default: none, [ The show and set rules that will be applied to the document ],
+  "rules",
+  [`<function>`],
+  default: none,
+  [ The show and set rules that will be applied to the document ],
 )
 #def-arg(
-  "cover", [`<function>`], default: none, [ A function that returns the cover of the notebook. Must take context as input. ],
+  "cover",
+  [`<function>`],
+  default: none,
+  [ A function that returns the cover of the notebook. Must take context as input. ],
 )
 #def-arg(
-  "frontmatter-entry", [`<function>`], default: none, [ A function that returns a frontmatter entry. Must take context and body as
+  "frontmatter-entry",
+  [`<function>`],
+  default: none,
+  [ A function that returns a frontmatter entry. Must take context and body as
     input. ],
 )
 #def-arg(
-  "body-entry", [`<function>`], default: none, [ A function that returns a body entry. Must take context and body as input. ],
+  "body-entry",
+  [`<function>`],
+  default: none,
+  [ A function that returns a body entry. Must take context and body as input. ],
 )
 #def-arg(
-  "appendix-entry", [`<function>`], default: none, [ A function that returns a appendix entry. Must take context and body as input. ],
+  "appendix-entry",
+  [`<function>`],
+  default: none,
+  [ A function that returns a appendix entry. Must take context and body as input. ],
 )
 
 === Context <context>
@@ -112,20 +143,46 @@ Context is stored as a dictionary with the following fields:
 
 #def-arg("title", [`<string>`], default: none, [The title of the entry])
 #def-arg(
-  "type", [`<string>` or `<none>`], default: none, [The type of the entry. This value is used differently by different templates.
+  "type",
+  [`<string>` or `<none>`],
+  default: none,
+  [The type of the entry. This value is used differently by different templates.
     Refer to the template level documentation to see what this means for your theme.],
 )
 #def-arg(
-  "start-date", [`<datetime>`], default: none, [The date at which the entry started.],
+  "start-date",
+  [`<datetime>`],
+  default: none,
+  [The date at which the entry started.],
 )
 #def-arg(
-  "end-date", [`<datetime>`], default: none, [The date at which the entry ended.],
+  "end-date",
+  [`<datetime>`],
+  default: none,
+  [The date at which the entry ended.],
 )
 #def-arg(
-  "page-number", [`<integer>` or `<none>`], default: none, [The page number of the first page of the entry. Only available while using the `print-toc()` utility
-  function. ],
+  "page-number",
+  [`<integer>` or `<none>`],
+  default: none,
+  [The page number of the first page of the entry. Only available while using the
+  `print-toc()` utility function. ],
 )
 
+== Default Theme
+
+The default theme.
+
+#warning[
+  This theme is very minimal, and is generally intended as a fallback for stuff
+  that other themes don't implement.
+]
+
+=== Components
+
+#let default-components-module = tidy.parse-module(read("./themes/default/components.typ"))
+#show-module(default-components-module, first-heading-level: 3)
+
 == Radial Theme
 
 The Radial theme is a minimal theme focusing on nice, rounded corners.
@@ -149,6 +206,10 @@ types are available:
 Minimal starting point:
 
 ```typ
+// Import the template and theme here
+
+#show: notebook.with(theme: radial-theme)
+
 #create-frontmatter-entry(title: "Table of Contents")[
   #components.toc()
 ]
@@ -186,7 +247,7 @@ Minimal starting point:
   for name in names.pos() {
     read(predicate + name + ".typ")
   }
-} 
+}
 
 === Components
 
@@ -219,7 +280,7 @@ types are available:
 - `"brainstorm"`: For entries about the brainstorm stage of the engineering design
   process.
 - `"decide"`: For entries about the decide stage of the engineering design
-  process.
+  process/
 - `"build"`: For entries about the build stage of the engineering design process.
 - `"program"`: For entries about the programming stage of the engineering design
   process.
@@ -234,7 +295,7 @@ Minimal starting point:
 
 #create-body-entry(title: "Day 1", type: "identify", date: datetime(year: 1984, month: 1, day: 1))[
   = Heading
-  
+
   #lorem(50)
 
   #components.pro-con(
@@ -257,7 +318,7 @@ Minimal starting point:
 
 #create-body-entry(title: "Day 2", type: "identify", date: datetime(year: 1984, month: 1, day: 2))[
   = Another Heading
-  
+
   #lorem(50)
 
   #components.decision-matrix(
@@ -343,8 +404,8 @@ guidelines, check our `CONTRIBUTING.MD` file in our GitHub.
 This section of the document covers how to add your own theme to the template.
 The first thing you'll have to do is create the entry point for your theme.
 Create a new directory inside the `themes/` directory, then create a Typst
-source file inside of that directory. For example, if you had a theme called `foo`,
-the path to your entry point would look like this: `themes/foo/foo.typ`.
+source file inside of that directory. For example, if you had a theme called
+`foo`, the path to your entry point would look like this: `themes/foo/foo.typ`.
 
 Once you do this, you'll have to add your theme to the `themes/themes.typ` file
 like this:
@@ -445,8 +506,8 @@ Once you define all of your functions you'll have to actually define your theme.
 The theme is just a dictionary which stores all of the functions that you just
 defined.
 
-The theme should be defined in your theme's entry point (`themes/foo/foo.typ` for
-this example).
+The theme should be defined in your theme's entry point (`themes/foo/foo.typ`
+for this example).
 
 Here's what the theme would look like in this scenario:
 

docs.typ

@@ -50,10 +50,41 @@
 }
 
 /// Variant of the `#create-entry()` function that creates a frontmatter entry.
+///
+/// *Example Usage:*
+///
+/// ```typ
+/// #create-frontmatter-entry(title: "Title")[
+///   #lorem(50)
+/// ]
+/// ```
+///
 #let create-frontmatter-entry = create-entry.with(section: "frontmatter")
 
 /// Variant of the `#create-entry()` function that creates a body entry.
+///
+/// *Example Usage:*
+///
+/// ```typ
+/// #create-body-entry(
+///   title: "Title",
+///   date: datetime(year: 2024, month: 1, day: 1),
+///   type: "identify", // Change this depending on what your theme allows
+///   author: "Bobert",
+///   witness: "Bobernius",
+/// )[
+///   #lorem(50)
+/// ]
+/// ```
 #let create-body-entry = create-entry.with(section: "body")
 
 /// Variant of the `#create-entry()` function that creates an appendix entry.
+///
+/// *Example Usage:*
+///
+/// ```typ
+/// #create-appendix-entry(title: "Title")[
+///   #lorem(50)
+/// ]
+/// ```
 #let create-appendix-entry = create-entry.with(section: "appendix")

entries.typ

@@ -1,6 +1,7 @@
-#import "@preview/tidy:0.1.0"
+#import "@preview/tidy:0.2.0"
 #import "@preview/codly:0.2.0"
 #import "@preview/tablex:0.0.8"
 #import "@preview/showybox:2.0.1"
 #import "@preview/timeliney:0.0.1"
 #import "@preview/cetz:0.2.0"
+#import "@preview/gentle-clues:0.6.0"

packages.typ

@@ -7,6 +7,7 @@
 
 /// A message in a colored box meant to draw the reader's attention.
 ///
+///
 /// - type (string): The type of admonition.
 ///   Available types include:
 ///   - "note"
@@ -23,10 +24,16 @@
 
   showybox(
     frame: (
-      border-color: info.color, body-color: info.color.lighten(80%), thickness: (left: 4pt), radius: 1.5pt,
-    ), [
+      border-color: info.color,
+      body-color: info.color.lighten(80%),
+      thickness: (left: 4pt),
+      radius: 1.5pt,
+    ),
+    [
       #text(
-        size: 15pt, fill: info.color, [
+        size: 15pt,
+        fill: info.color,
+        [
           #box(baseline: 30%, image.decode(colored-icon, width: 1.5em)) *#info.title*
         ],
       )

themes/radial/components/admonitions.typ

@@ -1,4 +1,4 @@
-#import "../colors.typ": *
+#include "../colors.typ"
 
 /// A table displaying pros and cons.
 ///