diff --git a/docs/book.toml b/docs/book.toml index bd0299f..a23b415 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -3,7 +3,7 @@ authors = ["BattleCh1cken"] language = "en" multilingual = false src = "src" -title = "notebookinator" +title = "The Notebookinator" [preprocessor.admonish] command = "mdbook-admonish" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index bbb63c7..f4971d5 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,7 +1,11 @@ # Summary -- [Introduction](./introduction.md) +[Introduction](./introduction.md) + - [Installation](./installation.md) - [Basic Usage](./basic_usage.md) - [API Reference](./reference.md) -- [Developer Documentation](./developer_documentation.md) +- [Developer Documentation](./developer_documentation/developer_documentation.md) + - [Project Architecture](./developer_documentation/project_architecture.md) + - [Making Your Own Theme](./developer_documentation/custom_themes.md) + - [Contributing a Theme](./developer_documentation/theme_contribution.md) diff --git a/docs/src/developer_documentation.md b/docs/src/developer_documentation.md index 02bf0fd..4796167 100644 --- a/docs/src/developer_documentation.md +++ b/docs/src/developer_documentation.md @@ -1,228 +1 @@ # Developer Documentation - -## Project Architecture - -The Notebookinator is split into two sections, the base template, and the -themes. The base template functions as the backend of the project. It handles -all of the information processing, keeps track of global state, makes sure page -numbers are correct, and so on. It exposes the main API that the user interacts -for creating entries and creating glossary entries. - -The themes act as the frontend to the project, and are what the user actually -sees. The themes expose an API for components that need to be called directly -inside of entries. This could include things like admonitions, charts, and -decision matrices. - -## File Structure - -- `lib.typ`: The entrypoint for the whole template. -- `internals.typ`: All of the internal function calls that should not be used by - theme authors or users. -- `entries.typ`: Contains the user facing API for entries, as well as the internal - template functions for printing out the entries and cover. -- `glossary.typ`: Contains the user facing API for the glossary. -- `globals.typ`: Contains all of the global variables for the entire project. -- `utils.typ`: Utility functions intended to help implement themes. -- `themes/`: The folder containing all of the themes. - - `themes.typ`: An index of all the themes are contained in the template -- `docs.typ`: The entry point for the project documentation. -- `docs-template.typ`: The template for the project documentation. - -## Implementing Your Own Theme - -The following section covers how to add a theme to the ones already in the -template. It only covers how to write the code, and not how to get it merged -into the main project. If you want to learn more about our contributing -guidelines, check our `CONTRIBUTING.MD` file in our GitHub. - -### Creating the Entry Point - -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`. - -Once you do this, you'll have to add your theme to the `themes/themes.typ` file -like this: - -```typ -#import `./foo/foo.typ` -``` - -Do not use a glob import, we don't want to pollute the namespace with the -functions in the theme. - -### Implementing Theme Functions - -Next you'll have to implement the functions contained inside the theme. These -functions are all called internally by the template. While we recommend that you -create implementations for all of them, if you omit one the template will fall -back on the default theme. - -The first functions you should implement are the ones that render the entries. -You'll need three of these, one for each type of entry (frontmatter, body, and -appendix). - -Each of these functions must take a context parameter, and a body parameter. The -context parameter provides important information, like the type of entry, and -the date it was written at. The body parameter contains the content written by -the user. - - - -The template expects that each of these functions returns a `#page()` as -content. - -Here's a minimal example of what these functions might look like: - -```typ -#let frontmatter-entry(ctx: (:), body) = { - show: page.with( - header: [ = Frontmatter header ], - footer: counter(page).display("i") - ) - - body -} -``` - -```typ -#let body-entry(ctx: (:), body) = { - show: page.with( - header: [ = Body header ], - footer: counter(page).display("1") - ) - - body -} -``` - -```typ -#let appendix-entry(ctx: (:), body) = { - show: page.with( - header: [ = Appendix header ], - footer: counter(page).display("i") - ) - - body -} -``` - -Next you'll have to define the rules. This function defines all of the global -configuration and styling for your entire theme. This function must take a doc -parameter, and then return that parameter. The entire document will be passed -into this function, and then returned. Here's and example of what this could -look like: - -```typ -#let rules(doc) = { - set text(fill: red) // Make all of the text red - - doc // Return the entire document -} -``` - -Then you'll have to implement a cover. The only required parameter here is a -context variable, which stores information like team number, game season and -year. - -Here's an example cover: - -```typ -#let cover(ctx: (:)) = [ - #set align(center) - *Foo Cover* -] -``` - -### Defining the Theme - - -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). - -Here's what the theme would look like in this scenario: - -```typ -#let foo-theme = ( - // Global show and set rules - rules: rules, - - cover: cover, - - // Entry pages - frontmatter-entry: frontmatter-entry, - body-entry: body-entry, - appendix-entry: appendix-entry -) -``` - -### Preparing Your Components - -With your base theme done, you may want to create some additional components for -you to use while writing your entries. This could be anything, including graphs, -tables, Gantt charts, or anything else your heart desires. To create a standard -theme, we recommend the following components: - -- Table of contents `toc()` -- Decision matrix: `decision-matrix()` -- Pros and cons table: `pro-con()` -- Glossary: `glossary()` - -First, you need to create a namespace to store all of your components like so: - -`themes/foo/components/` - -We recommend creating a `components.typ` file so you can glob import each component, -especially if you plan to implement a lot: - -`components/components.typ` - -Inside the components directory, create your three basic component files (the table of -contents, decision matrix, pros and cons table, and glossary). Then, glob import each -file in the `components.typ` file. - -```typ -#import "toc.typ": * -#import "decision-matrix.typ": * -#import "pro-con.typ": * -#import "glossary.typ": * -``` - -To render each component, you need to define a function inside the designated component -file. Note that, if these functions are left blank, the Notebookinator will render the -Default Theme component if applicable. - -The following is an example for the table of contents component: - -```typ -#let toc() = { - // You will customize the table of contents here later. -} -``` - -Finally, import the `components.typ` file where you defined your theme function (in this -case, `themes/foo/foo.typ`). - -```typ -#import "components/components.typ": * - -#let foo-theme = ( - ... -) -``` - -### Creating Components - - - -## Implementing a Private Theme - -This section will explain how to create your own theme locally, without adding it -to the Notebookinator. This process is similar to that of the -[Implementing Your Own Theme](#implementing-your-own-theme) section \ No newline at end of file diff --git a/docs/src/developer_documentation/custom_themes.md b/docs/src/developer_documentation/custom_themes.md new file mode 100644 index 0000000..1c2ccd7 --- /dev/null +++ b/docs/src/developer_documentation/custom_themes.md @@ -0,0 +1,259 @@ +# Making Your Own Theme + +If you're unhappy with the existing themes, or just want to add your own flair to your notebook, the Notebookinator supports custom themes. We highly recommend you familiarize yourself with the [Typst Documentation](typst.app/docs) before trying to implement one yourself. + +Themes consist of two different parts, the theme itself, and its corresponding components. + +The theme is just a dictionary containing functions. These functions specify how the entries and cover should look, as well as global rules for the whole document. We'll cover the required structure of this variable in a [later](#the-theme-variable) section. + +Components are simply functions stored in a module. These functions contain things like pro/con tables and decision-matrices. Most components are just standalone, but the Notebookinator does supply some utility functions to help with implementing harder components. Implementing components will be covered in [this](#writing-components) section. + +## File Structure + +The first thing you'll need to do is create a folder for your theme, somewhere in your notebook. As an example, lets create a theme called `foo`. The first thing we'll want to do is create a folder called `foo/`. Then, inside that folder, we'll want to create a file called `foo.typ` inside the `foo/` folder. This will be the entry point for your theme, and will contain your theme variable. + +Then, we'll want to create a `foo/components/components.typ` file. This file will contain all of your components. We recommend having each component inside of its own file. For example, an `example-component` might be defined in `foo/components/example-component.typ`. + +You'll also want to create an `entries.typ` file to contain all of your entry functions for your theme variable, and a `rules.typ` to store your global rules. + +Your final file structure should look like this: + +- `foo/` + - `foo.typ` + - `entries.typ` + - `rules.typ` + - `components/` + - `components.typ` + +```admonish info +This is just the recommended file structure, as long as you expose a theme variable and components, your theme will work just like all the others. You can also add any additional files as you wish. +``` + +## The Theme Variable + +Now that you've created your files, you can begin writing your theme. The first thing you should do is create a theme variable. Going back to our `foo` example, lets create a `foo-theme` variable in our `foo/foo.typ` file. + +```typ +// foo/foo.typ + +#let foo-theme = (:) // currently a blank dictionary +``` + +Currently our theme is blank, and will do nothing. If we try to apply it right now, all functions will fall back onto the `default-theme`. + +### Creating The Entries + +Now that we actually have a place to put our theme functions, we can start implementing our entry functions. + +Each of these functions has 2 requirements: + +- it must return a `page` function as output +- it must take a dictionary parameter named `ctx` as input, and a parameter called body. + +The `ctx` argument provides context about the current entry being created. This dictionary contains the following fields: + +- `title`: `str` +- `type`: `str` +- `date`: `datetime` +- `author`: `str` +- `witness`: `str` + +`body` contains the content the user has written. It should be passed into the `page` function in some shape or form. + +We'll write these functions in the `foo/entries.typ` file. Below are some minimal starting examples: + +### Frontmatter + +```typ +// foo/entries.typ + +#let frontmatter-entry(ctx: (:), body) = { + show: page.with( // pass the entire function scope into the `page` function + header: [ = ctx.title ], + footer: context counter(page).display("i") + ) + + body // display the users's written content +} +``` + +### Body + +```typ +// foo/entries.typ + +#let body-entry(ctx: (:), body) = { + show: page.with( + header: [ = Body header ], + footer: counter(page).display("1") + ) + + body +} +``` + +### Appendix + +```typ +// foo/entries.typ + +#let appendix-entry(ctx: (:), body) = { + show: page.with( + header: [ = Appendix header ], + footer: counter(page).display("i") + ) + + body +} +``` + +With the entry functions written, we can now add them to the theme variable. + +```typ +// foo/foo.typ + +// import the entry functions +#import "./entries.typ": frontmatter-entry, body-entry, appendix-entry + +// store the entry functions in the theme variable +#let foo-theme = ( + frontmatter-entry: frontmatter-entry, + body-entry: body-entry, + appendix-entry: appendix-entry, +) +``` + +### Creating a Cover + +Then you'll have to implement a cover. The only required parameter here is a +context variable, which stores information like team number, game season and +year. + +Here's an example cover: + +```typ +// foo/entries.typ + +#let cover(ctx: (:)) = [ + #set align(center) + *Foo Cover* +] +``` + +Then, we'll update the theme variable accordingly: + +```typ +// foo/foo.typ + +// import the cover along with the entry functions +#import "./entries.typ": cover frontmatter-entry, body-entry, appendix-entry + +#let foo-theme = ( + cover: cover, // store the cover in the theme variable + frontmatter-entry: frontmatter-entry, + body-entry: body-entry, + appendix-entry: appendix-entry, +) +``` + +### Rules + +Next you'll have to define the rules. This function defines all of the global +configuration and styling for your entire theme. This function must take a doc +parameter, and then return that parameter. The entire document will be passed +into this function, and then returned. Here's and example of what this could +look like: + +```typ +// foo/rules.typ + +#let rules(doc) = { + set text(fill: red) // Make all of the text red, across the entire document + + doc // Return the entire document +} +``` + +Then, we'll update the theme variable accordingly: + +```typ +// foo/foo.typ +#import "./rules.typ": rules // import the rules +#import "./entries.typ": cover frontmatter-entry, body-entry, appendix-entry + +#let foo-theme = ( + rules: rules, // store the rules in the theme variable + cover: cover, + frontmatter-entry: frontmatter-entry, + body-entry: body-entry, + appendix-entry: appendix-entry, +) +``` + +## Writing Components + +With your base theme done, you may want to create some additional components for you to use while writing your entries. This could be anything, including graphs, tables, Gantt charts, or anything else your heart desires. We recommend including the following components by default: + +- Table of contents `toc()` +- Decision matrix: `decision-matrix()` +- Pros and cons table: `pro-con()` +- Glossary: `glossary()` + +We recommend creating a file for each of these components. After doing so, your file structure should look like this: + +- `foo/components/` + - `components.typ` + - `toc.typ` + - `decision-matrix.typ` + - `pro-con.typ` + - `glossary.typ` + +Once you make those files, import them all in your `components.typ` file: + +```typ +// foo/components.typ + +// make sure to glob import every file +#import "./toc.typ": * +#import "./glossary.typ": * +#import "./pro-con.typ": * +#import "./decision-matrix.typ": * +``` + +Then, import your `components.typ` into your theme's entry point: + +```typ +// foo/foo.typ + +#import "./components/components.typ" // make sure not to glob import here +``` + +### Pro / Con Component + +### TOC Component + +### Decision Matrix Component + +### Glossary Component + +## Using the Theme + +Now that you've written the theme, you can apply it to your notebook. + +In the entry point of your notebook (most likely `main.typ`), import your theme like this: + +```typ +// main.typ + +#import "foo/foo.typ": foo-theme, components +``` + +Once you do that, change the theme to `foo-theme`: + +``` +// main.typ + +#show: notebook.with( + theme: foo-theme +) +``` diff --git a/docs/src/developer_documentation/developer_documentation.md b/docs/src/developer_documentation/developer_documentation.md new file mode 100644 index 0000000..6b6d466 --- /dev/null +++ b/docs/src/developer_documentation/developer_documentation.md @@ -0,0 +1,3 @@ +# Developer Documentation + +Welcome to the Notebookinator's developer documentation. This section is for advanced users who want to contribute to the Notebookinator's existing codebase, or want to use the existing tools at a more advanced level. diff --git a/docs/src/developer_documentation/project_architecture.md b/docs/src/developer_documentation/project_architecture.md new file mode 100644 index 0000000..649bac2 --- /dev/null +++ b/docs/src/developer_documentation/project_architecture.md @@ -0,0 +1,27 @@ +# Project Architecture + +The Notebookinator is split into two sections, the base template, and the +themes. The base template functions as the backend of the project. It handles +all of the information processing, keeps track of global state, makes sure page +numbers are correct, and so on. It exposes the main API that the user interacts +for creating entries and creating glossary entries. + +The themes act as the frontend to the project, and are what the user actually +sees. The themes expose an API for components that need to be called directly +inside of entries. This could include things like admonitions, charts, and +decision matrices. + +## File Structure + +- `lib.typ`: The entrypoint for the whole template. +- `internals.typ`: All of the internal function calls that should not be used by + theme authors or users. +- `entries.typ`: Contains the user facing API for entries, as well as the internal + template functions for printing out the entries and cover. +- `glossary.typ`: Contains the user facing API for the glossary. +- `globals.typ`: Contains all of the global variables for the entire project. +- `utils.typ`: Utility functions intended to help implement themes. +- `themes/`: The folder containing all of the themes. + - `themes.typ`: An index of all the themes are contained in the template +- `docs.typ`: The entry point for the project documentation. +- `docs-template.typ`: The template for the project documentation. diff --git a/docs/src/developer_documentation/theme_contribution.md b/docs/src/developer_documentation/theme_contribution.md new file mode 100644 index 0000000..578f1fa --- /dev/null +++ b/docs/src/developer_documentation/theme_contribution.md @@ -0,0 +1,3 @@ +# Contributing a Theme + +Once you've [written your theme](./custom_themes.md), you can contribute it to the Notebookinator, to be accessible to all other users. diff --git a/docs/src/installation.md b/docs/src/installation.md index 382c3c3..89b2f7c 100644 --- a/docs/src/installation.md +++ b/docs/src/installation.md @@ -24,7 +24,6 @@ Make sure you have the following software installed: - [Typst](https://github.com/casey/just#installation) - [Git](https://github.com/casey/just#installation) - [VSCode](https://code.visualstudio.com/) -- [just](https://github.com/casey/just#installation) Once you've installed everything, run the following commands: @@ -35,9 +34,7 @@ shell, like git-bash or the shell packaged with Cygwin or GitHub Desktop. ```bash git clone https://github.com/BattleCh1cken/notebookinator -cd notebookinator -just install -cd .. +./notebookinator/scripts/package @local rm -rf notebookinator ```