0.9.8	~~Nov 23, 2023~~

#169 in #website

GPL-3.0 license

275KB
663 lines

Cuteness is a static site generator. It generates a Rocket web-server and builds the Markdown[^4] source files. It was created to offer extreme configuration and an easy configuration API using TOML, and that's mainly what we're going to talk about here.

cuteconfig.toml
- [misc]
- [config]
The front-matter
- Example
Templating
- {{page.*}}
  - Example
- {{outer.*}}
  - Example
Source files
- SUMMARY.toml
Subcommands
- init
- build
- setup
- update
- clean
- uninstall
- help
Styles
- Using Sass
- Not using Sass
Routing
Preprocessors

`cuteconfig.toml`

cuteconfig.toml is the file used to store configuration settings. It's default configuration in the current version is: (latest version)

# cuteconfig.default.toml
[misc]
latex = true # Add KaTeX support
html_lang = "en" # HTML Language
syntax_highlighting = true

[config]
# Write here your custom templates!

`[misc]`

This section handles miscellaneous settings, usually related to preprocessors and very case-specific tools.

latex: Enables LaTeX[^1] equations.
html_lang: Changes the starting <html> tag (e.g. "es" <html lang="es">).
syntax_highlighting: Enables syntax highlighting using highlight.js.

`[config]`

This section is used to store user-provided configurations. It can store any TOML value (strings, integers, arrays...).

All these sections can be used in your documents with {{outer.*}} (e.g. {{outer.misc.html_lang}}), we'll see more about templating in the next section.

The front-matter

A front-matter is the initial heading before your Markdown contents. This heading contains some configuration options used to generate the webpage. Currently, the only mandatory field is title.

title: The current page's title.
pageconf (optional): User-provided page configuration (Key-value pairs).
additional_css (optional): Additional CSS files needed to properly render the page. (index.css is imported by default)

Example

# my_file.md
---
title: "My file"
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc est, semper non
maximus et, mattis in leo. Nullam luctus, ligula id venenatis consequat, ligula
odio convallis eros, sed scelerisque tortor elit vitae massa. Aliquam efficitur
tempus purus sit amet eleifend. Mauris vel ex iaculis, iaculis nisl id, finibus
justo. Morbi gravida vel velit eget ultricies. In orci purus, porta ut nibh
blandit, vestibulum lobortis augue. Vestibulum venenatis finibus tellus, sit amet
venenatis elit rutrum ut. Donec posuere ipsum efficitur tortor viverra dignissim.
Donec urna libero, molestie id libero vitae, bibendum rutrum leo. Praesent
suscipit tincidunt ultrices. Sed finibus neque blandit velit venenatis volutpat.
In id dui sit amet quam ullamcorper viverra. In rutrum ante sapien, et tincidunt
ligula dignissim id. Curabitur hendrerit sagittis orci, in rhoncus dui venenatis
sit amet. Nunc sed enim arcu.

In this case, the front-matter only contains title, that being "My file"

Templating

Cuteness uses Handlebars-rs[^3] and it exposes a templating API to the user with page and outer.

`{{page.*}}`

{{page.*}} is the interface that you can access in order to use page configuration. For example, you can use {{page.title}} to access the page's title.

Example

# my_file.md
---
title: "My file"
pageconf: {
    software-version: "0.7.2",
    status: "beta"
}
---

Now I can use {{page.title}} to access this page's title.
Currently, our software is in version {{page.pageconf.software-version}}, that means that we're in a {{page.pageconf.status}} version.

This will get rendered to:

<!-- [...] -->
<body>
    <div class="wrapper">
    <div class="cutesidebar">
        <ul>

            <li><a href="introduction">Chapter 1: Introduction</a></li>
        </ul>
    </div>
    <div class="main-content">
        <p>Now I can use My file to access this page’s title.
Currently, our software is in version 0.7.2, that means that we’re in a beta version. </p>
    </div>
</div>
</body>
<!-- [...] -->

`{{outer.*}}`

{{outer.*}} is the interface to use if you want to access global settings found in cuteconfig.toml.

Example

# cuteconfig.toml
# [...]
[config]
authors = [
    "Alejandra González",
    "Alejandra's cat, Keepy 🐱"
]
# [...]

# my_file.md
---
title: "My file"
---

Now I can list the authors of the page:

**Authors:**

{{#each outer.config.authors}}
    - {{this}}

{{/each}}

This will render to:

<!-- [...] -->
<body>
    <div class="wrapper">
    <div class="cutesidebar">
        <ul>

            <li><a href="introduction">Chapter 1: Introduction</a></li>
        </ul>
    </div>
    <div class="main-content">
        <p>Now I can list the authors of the page:</p>
<p><strong>Authors:</strong></p>
<p></p>
- Alejandra González
<p></p>
- Alejandra's cat, Keepy 🐱
<p></p>

    </div>
</div>
</body>

<!-- [...] -->

Source files

A normal file tree looks something like this:

.
├── cuteconfig.toml
├── src
│   └── introduction.md
│   └── [Other .md files]
└── SUMMARY.toml

All your Markdown files are located at the src directory; both cuteconfig.toml and SUMMARY.toml are located in the root directory. This is the default tree (generated by cuteness init) and it's the recommended way to start writing your contents.

When creating a new file, you'll have to start the file writing a front-matter and then the contents of your file. As explained in Templating, you can use Handlebars templates.

`SUMMARY.toml`

SUMMARY.toml is the file used to manage public links. The example SUMMARY.toml file (generated by cuteness init) looks like this:

[[map]]
title = "Chapter 1: Introduction"
url = "introduction"

It contains a table (map), this table can be used multiple times to define different routes (Indicated by [[ double brackets ]]).

[[map]]
title = "Chapter 1: ..."
# [...]

# Another page

[[map]]
title = "Chapter 2: ..."
# [...]

[[map]] tables contain some fields like title and url, the following section will explain them.

title: Page's title, this will be used for things such as the <title> tag in the HTML's head or the sidebar.
url: URL to the page, i. e. if the source page is at "<root>/src/my_file.md", write "my_file".

(Up-to-date version here)

Server routing and routes displayed to the user don't need to be the same.

Subcommands

`init`

cuteness init is the command used to initialize a dummy directory, ready to be written. It will create:

src directory.
introduction.md inside src with some default contents.
SUMMARY.toml in the root directory with default contents.
cuteconfig.toml in the root directory with default contents.

You can start by writing on introduction.md, then executing cuteness build, executing cargo run --manifest-path <output directory, default: www>/routing/Cargo.toml and going to http://localhost:8080/introduction

`build`

cuteness build is used to build the project, it will create an output directory containing the built version (using all your configurations) of your src directory. If there are .sass files in the directory src/styles it will also compile those.

`setup`

cuteness setup is a one-time command, it's used to get all necessary template files from the web. It requires internet connection. You can think of it as an enhanced git clone that only clones necessary files.

NOTE: This command will create a directory called cuteness-config at your Cargo home (usually ~/.cargo/ on Unix systems) and store there all your internal configurations. (Do not edit manually.)

`update`

cuteness update will update the internal templates and styles to the latest version; you can think of it as an enhanced git pull.

`clean`

cuteness clean will delete the output directory (default: www). It's not usually necessary.

`uninstall`

cuteness uninstall will delete the internal templating and styling files stored in <CARGO HOME>/cuteness-config/.

This will not uninstall the binary, you'll have to use cargo uninstall cuteness. This subcommand needs to be executed before doing that so it's a clean uninstall.

`help`

cuteness help displays a help message.

Styles

Styling files are stored at src/styles and can be imported in a per-page basis using the additional_css optional key on the page's front-matter.

The special built-in index.css file is always imported, this file contains basic layout options for the correct display of your page. You can check the Sass source of index.css here.

Using Sass

You can use Sass as a preprocessor for your files, just activate the feature sass when installing the binary (enabled by default) and store your .sass files in src/styles as any other .css file. They will be compiled with cuteness build.

Not using Sass

Almost the same, just locate your .css files at src/styles and they will not get compiled, but only copied to the output directory.

Routing

When using cuteness build, an output directory containing some static files and a simple web-server will be generated which you can access by going to http://localhost:8080/

As the project is still in development, efforts about using actual servers available on the internet are still very far from being started.

Preprocessors

The files content are preprocessed before being written, these preprocessors are used to change "straight quotes" to “curly quotes”, or to change emojicodes ":cat:" to actual emojis 🐱. These preprocessors are applied automatically and should not cause any problems.

[^1]: The tool specifically uses KaTeX, specialized on equations.

[^3]: Handlebars-rs uses the Handlebars templating language

[^4]: Specifically, our parser (pulldown-cmark) uses the CommonMark specification.

[^5]: There are some ideas about porting the generated web-server to Rust. As the project isn't v1.0 yet, this may change in the future.

Features

Feature documentation can be found on a rendered rustdoc page. This can be accessed through cargo doc.

License

This project uses the GNU General Public License v3.0. More information about licensing available in LICENSE.

Contributing

All contributions are greatly welcomed! A very useful contribution guide can be found at CONTRIBUTING.MD.

Dependencies

~13–23MB
~335K SLoC