Welcome to PageKit

PageKit is a versatile, high-performance web server designed to serve content from various sources, making it easy to publish websites directly from git repositories or a local directory. It is built with Python and FastAPI, offering a lightweight and powerful solution for personal and organizational web hosting.

Core Concepts

At its core, PageKit dynamically serves web content based on the incoming request. It can operate in different modes, allowing it to be a simple static site server for local development, a GitHub/Gitea Pages-like server for git repositories, or a full-fledged multi-tenant SaaS platform.

Key features include:

• Markdown-to-HTML Conversion: Automatically renders Markdown files as HTML pages.
• Jinja2 Templating: Uses the powerful Jinja2 templating engine to build dynamic and reusable layouts.
• Frontmatter Support: Extracts metadata (like title, author, layout) from Markdown files to use within templates.
• Flexible Configuration: Easily configured through environment variables.

Operating Modes

PageKit can be run in one of three modes, configured via the APP_MODE environment variable.

1. Repo Mode (APP_MODE="repo")

This is the default and most powerful mode. It serves content directly from a git repository (like Gitea). The server interprets the request's hostname to determine which organization and repository to pull content from.

Example: A request to my-org.pages.yourdomain.com will look for a repository (e.g., pagekit) within the my-org organization on your configured git instance.

2. Local Mode (APP_MODE="local")

Ideal for development, testing, or simple single-site hosting. In this mode, PageKit serves files directly from a specified local directory on the filesystem. It provides the same Markdown rendering and templating capabilities as the repo mode.

3. Platform Mode (APP_MODE="platform")

This mode is designed for multi-tenant, SaaS-like deployments. It will use a database to manage different users/organizations, allowing each to have their own repository configurations and access tokens.

Note: This mode is currently under development.

Configuration

PageKit is configured using an .env file in the project root.

Variable	Description	Required For	Default Value
APP_MODE	The operating mode. Can be repo, local, or platform.	All	"repo"
REPO_URL	The full URL to your git instance (e.g., https://gitea.example.com).	repo mode	(None)
REPO_TOKEN	A git API token with read-access to the repositories.	repo mode	(None)
DEFAULT_REPO	The default repository name to look for within an organization if not specified as a subdomain.	repo mode	"pagekit"
LOCAL_CONTENT_DIR	The absolute or relative path to the directory containing your content and templates for local serving.	local mode	(None)
DATABASE_URL	The connection string for the database.	platform mode	(None)
DEBUG	Set to true to enable debug logging and verbose error messages.	All	false

Getting Started

Running in Local Mode

1. Set the Environment Variables: In your .env file, configure the following:

   APP_MODE="local"
   LOCAL_CONTENT_DIR="docs" # Or your own content directory
   DEBUG=true
   

2. Create Content: Your LOCAL_CONTENT_DIR should contain your website's files (index.md, styles.css, etc.) and a templates directory for your Jinja2 layouts. See the examples/docs directory for an example structure.

3. Run the Server:

   uvicorn pagekit.main:app

   Visit http://localhost:8000 in your browser.

Running in Repo Mode

1. Set the Environment Variables: In your .env file, configure the following:

   APP_MODE="repo"
   REPO_URL="https://your-gitea-instance.com"
   REPO_TOKEN="your-secret-gitea-token"
   DEFAULT_REPO="my-website"
   DEBUG=true
   

2. Run the Server:

   uvicorn pagekit.main:app

3. Access Your Site: To access the content, you need to simulate a request with the correct hostname. You can do this by editing your local /etc/hosts file to point a custom domain to 127.0.0.1:

   127.0.0.1   my-org.localhost
   

   Then, visit http://my-org.localhost:8000 in your browser. PageKit will fetch content from the my-website repository in the my-org organization on your Gitea instance.

Content & Templating

Markdown and Frontmatter

Create content pages using Markdown. At the top of your .md file, you can include a YAML frontmatter block to define metadata.

Example: about.md

---
title: About Our Company
layout: layouts/page.html
author: John Doe
---

# Welcome to our page!

This is where you can write your content in Markdown...

• title: The title of the page, often used in the <title> tag or a heading.
• layout: Specifies which template file to use from the templates directory. If omitted, it defaults to layouts/page.html.
• Any other variables (e.g., author) are passed directly to the template.

Jinja2 Templates

Templates are located in the templates subdirectory of your content source (LOCAL_CONTENT_DIR or the git repo). You can use the full power of Jinja2 to create reusable layouts.

Example: templates/layouts/base.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ title }}</title>
</head>
<body>
    <header>
        <h1>{{ title }}</h1>
    </header>
    <main>
        {{ content | safe }}
    </main>
</body>
</html>

• {{ title }}: Renders the title from the frontmatter.
• {{ content }}: This is where the rendered HTML from your Markdown file will be injected. Use the | safe filter to ensure HTML is not escaped.

Deployment

For production, it is recommended to run PageKit as a Docker container, ideally within a Kubernetes cluster. The project includes a Dockerfile and sample Kubernetes manifests in the /k8s directory to get you started. Please refer to the README.md for more detailed deployment instructions.