siecje / htmd

Write Markdown and Jinja2 templates to create a website

htmd

htmd allows you to write Markdown and use templates to create a static website. Yes it is another static site generator.

Why another static site generator?

I admit I didn't try them all. I tried several static site generators written in Python, but I found them complicated. Some static site generators I tried created a template website with content on the home page but the index.html file had no content. It should be obvious where to find the content.

• I don't like starting with a lot of folders and files
• I want all blog posts in the same folder because it is easier to work with. I want the URL structure for each post to include the date (/2015/01/31/post-title), without having to create a folder for each year and month.
• I don't want to include all of the templates being used, only overwrite the ones I modified.
• I want it to be obvious where to find the content.
• I want it to be obvious how to set a value to use in multiple templates.
• If you made changes to one of your templates and ran build you wouldn't update existing files unless you deleted your build folder everytime.

I believe the reason there are so many static site generators is people are picky about their workflow and that's okay. This is also a great way to stay up to date with Packaging in Python.

What is the difference between posts and pages?

Posts are blog posts with dates and authors tracked by feeds. Pages are other webpages on the site, for example the About page.

How do I edit the layout of the site?

Edit the templates/_layout.html file that was created when running htmd start. This a Jinja 2 template that all other pages will use by default. You can add a link to CSS file that you have created in static/. To change other pages you will need to override the page template by creating a file with the same name in the templates/ folder. The complete list of templates can be found here.

How do drafts work?

A post will be a draft if draft: true is set in the metadata and will not appear in the build folder. If draft: build is set then the post page will be in the build but the post will not appear in any list pages. When a draft is built the metadata value will contain a UUID of where the post is available.

For example, if the draft metadata is draft: build|f47d4d98-9d66-448a-9e08-7b5c2032e558 then the post will served at /draft/f47d4d98-9d66-448a-9e08-7b5c2032e558/index.html.

To view the site as if all drafts were published run htmd preview --drafts.

Getting Started

$ pip install htmd

Commands:
  start      Create example files to get started.
  verify     Verify posts formatting is correct.
  build      Create static version of the site.
  preview    Serve files to preview site.
  templates  Create any missing templates

Development

Running the development version locally

$ git clone https://github.com/Siecje/htmd.git
$ python3 -m venv venv
$ venv/bin/python -m pip install pip setuptools --upgrade
$ venv/bin/python -m pip install -e htmd/[dev]
# You can now make changes inside htmd/ without having to re-install
$ mkdir my_site
$ cd my_site
$ ../venv/bin/htmd start
# You can also create a symlink to htmd
# somewhere on your $PATH and just use `htmd start`
$ ../venv/bin/htmd build

Running mypy

$ venv/bin/python -m mypy .

Running ruff

$ venv/bin/python -m ruff check --exclude typehints

Running the tests

$ git clone https://github.com/Siecje/htmd.git
$ cd htmd
$ python3 -m venv venv
$ venv/bin/python -m pip install pip setuptools --upgrade
$ venv/bin/python -m pip install -e .[dev]
$ venv/bin/python -m pytest .

Running the tests with coverage.py

$ venv/bin/coverage run --branch -m pytest .
$ venv/bin/coverage html --omit='/private/*'
$ open htmlcov/index.html

htmd's Issues

Sitemap

Create a sitemap when building.

Use template for Atom feeds

Remove feedwerk and use a simple template

Show coverage report html when coverage is not 100%

This will be helpful for new contributors.

An attempt has been made here.
https://github.com/Siecje/htmd/tree/ci_coverage_report

Editing styles doesn't reload htmd preview

With compiled styles htmd preview has to be restarted to see changes.

Remove tool.ruff.lint.per-file-ignores for test files

ruff doesn't see utils.py as a local import in test_build.py and test_verify.py

htmd/pyproject.toml

Lines 69 to 75 in 79c11f3

	[tool.ruff.lint.per-file-ignores]
	"tests/test_app.py" = ["ARG001"]
	"tests/test_build.py" = ["I001"]
	"tests/test_drafts.py" = ["ARG001", "I001"]
	"tests/test_post_dates.py" = ["I001"]
	"tests/test_preview.py" = ["I001"]
	"tests/test_verify.py" = ["I001"]

Analytics Guide

Add instructions on how to add analytics to you site.

Atom feed per tag

Generate multiple languages

Be able to create the site in multiple languages and have build/en/, build/fr/ etc.

Provide an example nginx config to show how to map to the correct version of the site.

Improve packaging

Currently zip_safe=False, this is because the example_site/ files are included in the package to be installed. They end up in the install directory.

Why can't they be in the zipped wheel?

Could use strings for them and write them to a new file instead of copying.

Remove old files from build

If you create a post and then build and then set the post to draft and build again the post which was added during the first build will still be there.

Fix done in
74060fd

Waiting for upstream fix Frozen-Flask/Frozen-Flask#138

Ad Guide

Tutorial on how to add ads

Remove ignore: type for jinja_loader

htmd/htmd/site.py

Line 117 in 4996f3d

app.jinja_loader = ChoiceLoader([ # type: ignore[assignment]

I believe the typehint in flask is incorrect.

pallets/flask#5388
pallets/flask#5389

Pretty JS

Don't use Python for config file

config.py is a Python file, but it could be a TOML file.

Then we can remove the option on coverage to exclude temp files.

Find htmd site root when running commands

Have any htmd command work inside an htmd project, find the project root and set it as cwd.

If you run htmd build inside the build directory, it won't work.

Re-create combined.min.css or combined.min.js for a new file

If a new .css file is created while htmd preview is running then combined.min.css should be re-created so the new styles will be available without restarting preview.

If a new .css file is created while htmd preview is running then combined.min.js should be re-created so the new JavaScript code will be available without restarting preview.

Partial work done in https://github.com/Siecje/htmd/tree/refresh

Improve Jekyll deployments

_reset.css starts with a underscore so that when it is combined it is first, but Jekyll ignores files that start with an underscore so this causes a problem with GitHub pages.

Could add a .nojekyll file on start but it is more of a deployment issue, but could include information about it in the docs.

https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/

Is this still an issue?

Pagination

Pages that use the _list.html template do not have pagination.

Pretty CSS

Register all posts and pages with Frozen-Flask

If the site no longer links to a post or page it will not be built and won't be in the build directory.

Provide a way register routes with Frozen-Flask in case links in templates are changed.

Draft Posts

Be able to set a post as a draft, ensure draft posts do not appear in lists.

Can build with a draft and deploy and link to the draft and get feedback before publishing.