Developing tantu

This guide explains how tantu is built, so you can change it with confidence.

Build and test

make          # builds ./tantu
make test     # builds with AddressSanitizer and UBSan, then runs tests/run.sh
make cosmo    # builds tantu.com, one file for Windows, macOS and Linux (needs cosmocc)
make clean

The tests use Python for a few checks. Install Pillow and pyftpdlib to run every test:

python3 -m pip install --user pillow pyftpdlib

Every push and pull request runs the tests on Linux and macOS with GitHub Actions.

How a build works

site.conf is read into a map (parse_conf in src/main.c).
Theme templates and partials are loaded from themes/<name>/.
Markdown files in content/posts and content/pages are read. Front matter becomes variables, the body becomes HTML (src/markdown.c).
Posts are sorted by date (newest first) or by the sort key in site.conf.
static/ is copied, and JPEG and PNG images get smaller versions (src/image.c, cached in .cache/images).
Each page gets its SEO tags (src/seo.c), an automatic social image if it has none (src/image.c, cached in .cache/og), and is rendered with its template (src/template.c).
sitemap.xml, robots.txt, feed.xml, search-index.json, .htaccess and _headers are written.

Source files

File	What it does
`src/main.c`	Commands, loading content, the build
`src/markdown.c`	Safe Markdown to HTML. Raw HTML is always escaped
`src/template.c`	`{{ var }}`, `{{{ raw }}}`, `{{#if}}`, `{{#each}}`, `{{> partial}}`
`src/seo.c`	Meta tags, Open Graph, JSON-LD, sitemap, feed, security headers
`src/image.c`	Resizing and social images, using the stb libraries
`src/dashboard.c`	The dashboard server and its API
`src/serve.c`	The local preview server
`src/ftp.c`	FTP publishing
`src/zip.c`	ZIP export and CRC-32
`src/util.c`	Strings, files, folders and a small map
`src/embedded_api.c`	Reads files compiled into the program
`ui/dashboard.html`	The dashboard page
`tools/embed.c`	Turns themes, starters, ui and assets into `src/embedded.c`

src/embedded.c is generated by make and not stored in Git.

Adding a schema type

Schema is written in seo_head in src/seo.c. The type comes from home_schema or post_schema in site.conf, or schema in a page's front matter. Add a branch for your type next to Event, Course and Service, add a starter site that uses it, and add it to the JSON-LD check in tests/run.sh.

Adding a theme

See THEMES.md.

Rules for code

C11, no compiler extensions, no new outside libraries unless they are single-file and public domain or MIT
Build without warnings using -Wall -Wextra -Wpedantic
Escape everything that goes into HTML (esc_html) or JSON (esc_json)
Never let the finished site depend on server code: it must work on shared hosting and static hosts
Keep user-facing text plain and short

Updating the docs website

The guides in docs/ are also published as web pages at mmrahmanbappi.github.io/tantu-c-framework/docs/. After you edit a guide, rebuild the pages and commit both files:

python3 -m pip install --user markdown
python3 tools/build-docs.py

Edit the .md file, never the .html file, because the script writes the HTML again each time.

Making a release

Update VERSION in src/main.c and GENERATOR in src/seo.c.
Update README and docs/PLAN.md.
Push a tag: git tag v1.1.0 && git push origin v1.1.0. The release workflow builds, tests and uploads the files.

This page is made from docs/DEVELOPING.md. Spotted a mistake? Open an issue or send a pull request on GitHub.