Foldsite
Foldsite is a dynamic site generator built with Python and Flask. It allows you to create and manage a website using Markdown content, HTML templates, and CSS styles.
Table of Contents
- Foldsite
Configuration
The configuration file is written in TOML format and contains various settings for the application. Below is an example configuration file (config.toml):
[paths]
content_dir = "example/content"
templates_dir = "templates"
styles_dir = "styles"
[server]
listen_address = "127.0.0.1"
listen_port = 8080
debug = false
access_log = true
max_threads = 4
admin_browser = false
admin_password = "your_admin_password"
Template Setup
Templates are HTML files that define the structure of your web pages. They are stored in the templates directory. Each template can include other templates and use Jinja2 syntax for dynamic content.
Site Setup
The site content is stored in the content directory. Each Markdown file represents a page on your site. The directory structure of the content directory determines the URL structure of your site.
Style Setup
Styles are CSS files that define the appearance of your web pages. They are stored in the styles directory. You can create specific styles for different types of content and categories.
Template and Style Search
Templates and styles are searched in a specific order to apply the most specific styles first, followed by more general styles, and finally the base style.
How a Template is Written
Templates are written in HTML and use Jinja2 syntax for dynamic content. Below is an example template (base.html):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ title }}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='base.css') }}">
{% for style in styles %}
<link rel="stylesheet" href="{{ style }}">
{% endfor %}
</head>
<body>
<div class="content">
{{ content }}
</div>
</body>
</html>
Jinja Primer
Jinja2 is a templating engine for Python. It allows you to include dynamic content in your HTML templates. Below are some basic Jinja2 syntax examples:
- Variables:
{{ variable }} - Loops:
{% for item in list %} ... {% endfor %} - Conditionals:
{% if condition %} ... {% endif %} - Includes:
{% include 'template.html' %}
Added Tools for the Template
Foldsite provides additional tools for templates, such as functions to get sibling content files, text document previews, and folder contents.
Tool Input and Return Types
get_sibling_content_files(path: str) -> list
Returns a list of sibling content files in the specified directory.
get_text_document_preview(path: str) -> str
Generates a preview of the text document located at the given path.
get_sibling_content_folders(path: str) -> list
Returns a list of sibling content folders within a specified directory.
get_folder_contents(path: str) -> list
Retrieves the contents of a folder and returns a list of TemplateFile objects.
Example Usages for Tools and Types
Example Usage of get_sibling_content_files
<ul>
{% for file in get_sibling_content_files('path/to/directory') %}
<li>{{ file[0] }} - {{ file[1] }}</li>
{% endfor %}
</ul>
Example Usage of get_text_document_preview
<div>
{{ get_text_document_preview('path/to/document.md') }}
</div>
Example Usage of get_sibling_content_folders
<ul>
{% for folder in get_sibling_content_folders('path/to/directory') %}
<li>{{ folder[0] }} - {{ folder[1] }}</li>
{% endfor %}
</ul>
Example Usage of get_folder_contents
<ul>
{% for item in get_folder_contents('path/to/directory') %}
<li>{{ item.name }} - {{ item.path }}</li>
{% endfor %}
</ul>
Deployment
To deploy Foldsite, you can use Docker. Below is an example Dockerfile:
FROM python:3.13.2-bookworm
WORKDIR /app
COPY requirements.txt requirements.txt
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]
Docker Compose Example
Below is an example docker-compose.yml file to deploy Foldsite using Docker Compose:
version: '3.8'
services:
foldsite:
build: .
ports:
- "8080:8080"
volumes:
- .:/app
environment:
- CONFIG_PATH=config.toml