Valerie's Tech Writer Garden

Zensical

2 min read

Zensical is one of many Static Site Generators for technical Documentation. It is the official successor to MkDocs Material theme.

Resources

Features

  • Same feature set as MkDocs + Material theme
  • Compatible with MkDocs Material setups
  • Will probably support the most popular mkdocs plugins in the future, see Backlog

Use Zensical in a Container

The following Docker commands are for the Windows command line tool:

docker run --rm -it -v "%cd%:/docs" -w /work zensical/zensical <command>

Explanation:

  • docker run creates and starts a container from an image.
    • If the image is not present → Docker pulls it
    • If it is present → Docker starts it immediately
  • --rm automatically deletes the container when it stops.
    • No clutter in Docker Desktop
    • No “stopped containers” piling up
    • Your project files are safe because they live on your machine
  • -it is actually two flags combined:
    • -i → interactive keeps STDIN open so the container can receive input.
    • -t → terminal allocates a pseudo-terminal so output looks normal (colors, prompts, etc.).
    • You can see logs
    • You can stop the server with Ctrl+C
    • You can interact with the process
  • -p 8000:8000 is the port mapping (HOST_PORT : CONTAINER_PORT or port on your machine and port inside the container)
  • -v "%cd%:/docs" is the volume (bind mount)
    • %cd% is a Windows CMD variable representing the current directory on your machine
    • :/docs is the path inside the container
    • :/work the working directory inside the container
  • zensical/zensical is is the Docker image name (Docker Hub user / Image name).

To use Zensical inside Docker (Containers):

  1. Pull the official Docker image: docker pull zensical/zensical.
  2. Create a new folder for your project: mkdir my-zensical-project and cd my-zensical-project.
  3. Create a new Zensical project using the Docker image: docker run --rm -it -v "%cd%:/docs" -w /work zensical/zensical new .
  4. Edit your project, work on it, do your regular workflows.
  5. Start the Zensical web server to serve a preview of your project: docker run --rm -it -p 8000:8000 -v "%cd%:/docs" zensical/zensical.
  6. Build your project: `docker run —rm -it -v “%cd%:/docs” -w /work zensical/zensical build´.

Note

You could create the project inside Docker only, but then:

  • Files live inside the container
  • You must docker cp them out later
  • Container removal deletes your work

Graph View