Customizing Stattic: Command-Line Arguments for Stattic
Stattic is a flexible static site generator that lets you customize the way your site is built through a variety of command-line arguments. These arguments allow you to minify files, choose fonts, change the number of posts per page, and more.
In this post, we'll go through some of the most useful command-line arguments you can use with Stattic to tailor the build process to your needs.
Basic Usage
To start with, let's look at the basic command to build your site with Stattic:
python3 stattic.py --output=output
This command will build your site and save the generated files into the output folder.
But there's so much more you can do! Let's dive into the different arguments you can use.
Using the --minify Flag
One of the most useful features of <a href="/">Stattic</a> is the ability to minify all of your CSS and JavaScript files with the --minify flag. This is great for production environments where you want to reduce the file size of your assets for faster page load times.
Example Usage:
python3 stattic.py --output=output --minify
This will:
- Combine all CSS files into a single
main.min.cssfile. - Combine all JavaScript files into a single
main.min.jsfile. - Ensure that your base.html template includes these minified files.
What Happens Under the Hood?
When the --minify flag is used, Stattic will concatenate and minify all CSS and JS files in the assets folder, creating a main.min.css and main.min.js in the output/assets folder. These minified files are automatically referenced in the HTML files instead of the uncompressed versions.
Adding Google Fonts with --fonts
Want to include Google Fonts in your site? Stattic lets you specify which fonts to download using the --fonts argument. By default, the Quicksand font is used but you are able to override it with your own fonts.
Example Usage:
python3 stattic.py --output=output --fonts="Roboto,Open+Sans"
This command will download the specified fonts (in this case, Roboto and Open Sans) and automatically generate CSS files to use them in your site.
How It Works:
- Stattic fetches the fonts from the Google Fonts API.
- It saves the fonts locally in the
output/assets/fonts/directory. - A CSS file (
fonts.css) is generated that includes@font-facerules for each specified font and their various weights.
You can then apply these fonts using the generated classes (e.g., .roboto-400, .open-sans-300).
Applying Custom Fonts in HTML
Once you've added your fonts using the --fonts argument, you can easily apply them in your HTML templates by using the class names generated by Stattic.
For example, to apply Roboto 400 to a heading:
`<h1 class="roboto-400">Welcome to My Site</h1>`
Customizing the Number of Posts per Page with --posts-per-page
By default, Stattic shows 5 posts per page, but you can change this using the --posts-per-page argument.
Example Usage:
python3 stattic.py --output=output --posts-per-page=10
This will generate pages that show 10 posts at a time, instead of the default 5.
How It Works:
Stattic will paginate your posts, creating multiple pages (if necessary) based on the number of posts you choose to display. This is particularly useful if you have a blog with a lot of content and want to limit the number of posts on the homepage or archive pages.
Sorting Posts by Date, Title, or Author with --sort-by
You can also change the way posts are sorted using the --sort-by argument. You can sort posts by date, title, or author.
Example Usage:
python3 stattic.py --output=output --sort-by=title
This will sort the posts alphabetically by their title when building the site.
Available Options:
--sort-by=date(default)--sort-by=title--sort-by=author
Watching for File Changes with --watch
If you're actively developing a site and making frequent changes, the --watch flag is a huge time-saver. It automatically rebuilds the site whenever you change a content file.
Example Usage:
python3 stattic.py --output=output --watch
With this command, Stattic will continue running in the background, watching for changes to your Markdown, template, or asset files. Whenever it detects a change, it will rebuild the site automatically, so you don't need to run the build command manually each time.
Combining Multiple Arguments
You can combine multiple arguments to customize your build even further. For example, you can download fonts, set the number of posts per page, and enable minification all at once:
Example Usage:
python3 stattic.py --output=output --minify --fonts="Lato,Montserrat" --posts-per-page=8 --sort-by=date
This will:
- Minify all CSS and JS files.
- Download the Lato and Montserrat fonts.
- Display 8 posts per page.
- Sort posts by date.
Summary of Useful Arguments
Here's a quick reference for some of the most useful command-line arguments in Stattic:
<table> <thead> <tr> <th>Argument</th> <th>Description</th> <th>Example Usage</th> </tr> </thead> <tbody> <tr> <td><code>--output=<path></code></td> <td>Specify the output directory for the generated site.</td> <td><code>--output=output</code></td> </tr> <tr> <td><code>--minify</code></td> <td>Minify CSS and JS into single files.</td> <td><code>--minify</code></td> </tr> <tr> <td><code>--fonts=<fonts></code></td> <td>Download and include Google Fonts.</td> <td><code>--fonts="Lato, Montserrat"</code></td> </tr> <tr> <td><code>--posts-per-page=<num></code></td> <td>Set the number of posts to display per page.</td> <td><code>--posts-per-page=10</code></td> </tr> <tr> <td><code>--sort-by=<option></code></td> <td>Sort posts by date, title, or author.</td> <td><code>--sort-by=title</code></td> </tr> <tr> <td><code>--watch</code></td> <td>Watch for file changes and automatically rebuild.</td> <td><code>--watch</code></td> </tr> </tbody> </table>
Additional Features in Stattic
Logging System
Stattic includes a robust logging system that records both INFO and DEBUG level logs. Logs are saved in a /logs folder with a timestamped filename. The logs can help in debugging and monitoring the build process.
Image Conversion to WebP
Stattic automatically downloads images referenced in your markdown content and converts them to WebP format for optimal performance. These images are stored in the output/images/ folder, and the URLs in your content are replaced with local paths to the WebP versions.
Markdown to HTML Conversion with Mistune
Stattic uses the Mistune library to convert markdown content to HTML. Mistune supports various plugins, including:
- Task lists
- Tables
- Strikethrough text
This allows you to include advanced markdown features in your posts and pages.
Custom Templates for Posts and Pages
You can specify custom templates for individual posts or pages by adding a template field to the frontmatter of your markdown files. For example:
template: my_custom_template
Stattic will use the my_custom_template.html file from the templates directory when generating the HTML.
Categories, Tags, and Authors from YAML
Stattic loads categories, tags, and author information from YAML files located in the content/ directory. These YAML files allow you to organize your content more easily. Here's an example of how to define a category in categories.yml:
1:
name: "Category One"
2:
name: "Category Two"
In your posts, you can reference these categories by their ID:
categories:
- 1
- 2
The same applies to tags (tags.yml) and authors (authors.yml).
Static Pages
You can create static pages (such as a contact page) using templates. To generate static pages, Stattic uses the build_static_pages() method. An example page is the Contact page, which can be created by specifying a template like page.html:
<h1>Contact Us</h1><p>Contact page content goes here.</p>
Conclusion
Stattic is designed to be flexible and adaptable to your needs, and these command-line arguments help you get the most out of it.
Whether you're optimizing your site for production with --minify, or downloading your favorite Google Fonts with --fonts, you have complete control over the build process.
Feel free to experiment with these arguments and create a workflow that works best for you!
Happy building!