6 releases
1.0.0 |
|
---|---|
0.9.10 | Nov 23, 2023 |
0.9.8 | Mar 28, 2023 |
#1306 in Web programming
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
cuteconfig.toml
is the file used to store configuration settings. It's default configuration in the current version is: (latest version)
# cuteconfig.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 usinghighlight.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".
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
insidesrc
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
~337K SLoC