pagekit 0.2.1
Serve static sites directly from your repositories.
Requires Python: <4.0,>=3.14

# 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:**
    ```bash
    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:**
    ```bash
    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`**
```yaml
---
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`**
```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.