dubey/foldsite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity
foldsite/README.md

185 lines
5.7 KiB
Markdown
Raw Normal View History

start docs (AI) fix some caching logic
2025-03-15 15:55:40 -04:00
# 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
<!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`
```html
<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`
```html
<div>
{{ get_text_document_preview('path/to/document.md') }}
</div>
```
### Example Usage of `get_sibling_content_folders`
```html
<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`
```html
<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:
```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
```
Reference in New Issue Copy Permalink