An intentionally basic static site generator written in rust 🦀 with the help of nix ❄️
Calcite aims to be a middle ground between hacking away in html, as described in the html hobbyist, and wrangling a more complex framework like hugo or wordpress. The goal is to give users complete control of their theming while keeping their content separate.
Create two directories for your site, content and template.
The content directory must include at least one markdown, .md, file. The contents and structure of this directory will be copied to the out/ directory when built.
Template must include template.html, this file must contain a <div id="content"> and closing div tag. This tag is used to place the contents of the markdown file inside. A simple example of this file is as follows:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Title</title>
<meta charset="utf-8" />
<link rel="stylesheet" href="css/general.css" />
<link rel="shortcut icon" type="image/x-icon" href="media/favicon.ico">
</head>
<body>
<div>
<header>
<h1>Header</h1>
<!-- navbar -->
</header>
<div id="content">
<!-- markdown content will be turned into html and placed here -->
</div>
<footer>
<p>generic copyright</p>
</footer>
</div>
</body>
</html>Run nix run github:cartwatson/calcite/v0.0.0 in the directory you setup above
Remove v0.0.0 to run with the latest changes
Obligatory Security Warning, the best way to avoid said security issue is to pin to a version
- Create a github pages repo: github guide
- Create a file in your repo
.github/workflows/deploy.yml - Add the below code block to the
.github/workflows/deploy.ymlfile- make sure to add a version to
run: nix run github:cartwatson/calciteif desired
- make sure to add a version to
- Github will now automatically update your site every time you push more content or change your theme
name: "Build + Deploy with Calcite"
on:
push:
branches:
- gh-pages
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v4
- name: install nix
uses: cachix/install-nix-action@v31
- name: setup pages
id: pages
uses: actions/configure-pages@v5
- name: Build with calcite
run: nix run github:cartwatson/calcite
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./out
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4All other methods of install are currently unsupported. It's in the roadmap to generate binaries for Linux and MacOS for future releases.
Using Nix is the only supported development process.
- use
nix developto get all depencies for your editor - use
nix buildto build and link to your/nix/store, symlinked toresultin the current dir./result/bin/calcitein the same directory where you have yourtemplate/andcontent/directories
- use
nix-shell -p httplz --command "httplz out/"to serve the site locally (or use your favorite http server)
Create a content/test.md file. Ideally it includes a variety of md components, including nested components (ie code blocks inside blockquotes). Provided example below
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
<p>plain paragraph</p>
> blockquote
> blockquote with `inline code`
> blockquote with *bold*
```
code block
code block
code block
```
- bullet list
- bullet list
- bullet list
1. ordered list
2. ordered list
3. ordered list
[link](https://google.com)
regular ***bold + italic* just bold** regular
regular **bold** regular
regular *italic* regular
regular paragraph
regular paragraph
regular paragraph
Create a template/template.html file as described here
future features
- way to pull a theme from github, ie
nix run --theme=github:cartwatson/calcite-theme-gruvbox/v1.0.0; aim is to make deployment even more simple - annotation citations
- syntax highlighting in codeblocks
- allow template files in sub directories; eg
blog/template.html - easy copy from codeblocks
- debug mode/better logging
- add ability to link to headings, needs design work for how to copy links
- more markdown
- unordered lists
- ordered lists
v1.0.0
- available on nixpkgs - counting the ability to
nix run github:cartwatson/calciteas enough... - clean up code architecture, no more hacks
- if unsuccessful at anypoint, remove any artifacts created
- prompt remove output dir if it exists
- correct indentation on html files, use prettier probably
- more rules of CommonMark
- bold
- italic
- inline code
- code blocks
- blockquote
- images
- horizontal lines
- basic documentation on usage and themeing
v0.0.0 - beta
- basic static site generator, can generate a directory that can be hosted as a site
- adheres to enough rules of CommonMark
- headings
- paragraphs
- links
- get a good name for the project
- scope creep
- inline html pass through
- standalone html pass through
- github action template for easy pages deployment; see here
Calcite has a PH of 9.91 making it naturally pretty basic, also it's a great looking minecraft block