# 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](#foldsite) - [Table of Contents](#table-of-contents) - [Configuration](#configuration) - [Template Setup](#template-setup) - [Site Setup](#site-setup) - [Style Setup](#style-setup) - [Template and Style Search](#template-and-style-search) - [How a Template is Written](#how-a-template-is-written) - [Jinja Primer](#jinja-primer) - [Added Tools for the Template](#added-tools-for-the-template) - [Tool Input and Return Types](#tool-input-and-return-types) - [`get_sibling_content_files(path: str) -> list`](#get_sibling_content_filespath-str---list) - [`get_text_document_preview(path: str) -> str`](#get_text_document_previewpath-str---str) - [`get_sibling_content_folders(path: str) -> list`](#get_sibling_content_folderspath-str---list) - [`get_folder_contents(path: str) -> list`](#get_folder_contentspath-str---list) - [Example Usages for Tools and Types](#example-usages-for-tools-and-types) - [Example Usage of `get_sibling_content_files`](#example-usage-of-get_sibling_content_files) - [Example Usage of `get_text_document_preview`](#example-usage-of-get_text_document_preview) - [Example Usage of `get_sibling_content_folders`](#example-usage-of-get_sibling_content_folders) - [Example Usage of `get_folder_contents`](#example-usage-of-get_folder_contents) - [Deployment](#deployment) - [Docker Compose Example](#docker-compose-example) ## Configuration The configuration file is written in TOML format and contains various settings for the application. Below is an example configuration file (`config.toml`): ```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`): ```html {{ title }} {% for style in styles %} {% endfor %}
{{ content }}
``` ## 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` ```html ``` ### Example Usage of `get_text_document_preview` ```html
{{ get_text_document_preview('path/to/document.md') }}
``` ### Example Usage of `get_sibling_content_folders` ```html ``` ### Example Usage of `get_folder_contents` ```html ``` ## Deployment To deploy Foldsite, you can use Docker. Below is an example Dockerfile: ```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: ```yaml version: '3.8' services: foldsite: build: . ports: - "8080:8080" volumes: - .:/app environment: - CONFIG_PATH=config.toml ```