Installation and GitHub Actions

Install Webifier, render locally, and automate publishing from GitHub Actions.

Install

Webifier is a Python build tool. Installing webifier also installs the first-party extensions package used by the default renderers.

pip install webifier

During local development in this repository, the packages may be installed from adjacent checkouts instead. Published users should use the package name.

YAML

A small site usually starts with index.yml and a config block that enables the default extensions.

title: My Project

config:
  webifier:
    extensions:
      site:
        uses: webifier.standard
      markdown:
        uses: webifier.markdown
      notebook:
        uses: webifier.notebook
      search:
        uses: webifier.search
        content: true
        links: true
      theme:
        uses: webifier.theme
        default: system
        switcher: true

intro:
  label: Overview
  content: |
    # My Project

    Notes, notebooks, and reports from the repository.

Overview

My Project

Notes, notebooks, and reports from the repository.

Render

Run Webifier from the repository root:

webify --index index.yml --output webified --baseurl ""

Common options:

--index: the root YAML page.
--output: the generated static site directory.
--baseurl: URL prefix for deployment; use "" for a domain-root site.
--templates-dir: local template override directory.
--repo-full-name: repository name such as owner/repo, used by features that need GitHub context.

Preview the output with any static file server:

python -m http.server 4173 --directory webified

Action

Add .github/workflows/webifier.yml to build and deploy with GitHub Actions. The Webifier action installs Python and Webifier for you:

name: Build Webifier site

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Webify
        uses: webifier/build@v1.0.5
        with:
          baseurl: ""
          index: index.yml
          publish_dir: webified
          templates_dir: .
          # Optional: install extra extension packages before rendering.
          # extra-packages: my-webifier-extension

      - uses: actions/upload-pages-artifact@v3
        with:
          path: webified

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

If you prefer to call the CLI directly, replace the Webify step with:

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Webifier
        run: pip install webifier

      - name: Build site
        run: |
          webify \
            --repo-full-name "${{ github.repository }}" \
            --baseurl "" \
            --index index.yml \
            --output webified \
            --templates-dir .

If the site uses a custom extension, install it in the action too:

      - name: Webify
        uses: webifier/build@v1.0.5
        with:
          baseurl: ""
          index: index.yml
          publish_dir: webified
          templates_dir: .
          extra-packages: "my-extension @ git+https://github.com/me/my-extension.git"

Use one requirement per line when installing multiple extra packages:

          extra-packages: |
            my-extension
            another-extension

Syntax

Setup checklist:

Step	Command or file	Purpose
Install	`pip install webifier`	Installs the core package and first-party extensions.
Source page	`index.yml`	The root page Webifier starts from.
Local build	`webify --index index.yml --output webified --baseurl ""`	Generates static HTML into `webified/`.
Local preview	`python -m http.server 4173 --directory webified`	Serves the generated files during development.
Automation	`.github/workflows/webifier.yml`	Runs the same build on every push.
Custom extensions	`extra-packages: my-extension`	Installs extra extension packages in GitHub Actions.

Important index.yml keys:

Key	Meaning
`title`	Browser/page title.
`config.webifier.extensions`	Named extension instances to enable.
ordinary section keys	Page content rendered top to bottom.

Useful CLI flags:

Flag	Meaning
`--index index.yml`	Root YAML page.
`--output webified`	Generated static site directory.
`--baseurl ""`	URL prefix; empty string is common for root-domain deployments.
`--templates-dir .`	Look for site-local templates/assets beside `index.yml`.

Next