Tanishq Dubey
fc211edc77
All checks were successful
Datadog Secrets Scanning / Datadog Static Analyzer (push) Successful in 9s
Datadog Software Composition Analysis / Datadog SBOM Generation and Upload (push) Successful in 15s
Datadog Static Analysis / Datadog Static Analyzer (push) Successful in 19s
Release / build (release) Successful in 39s
185 lines
5.7 KiB
Markdown
185 lines
5.7 KiB
Markdown
# 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
|
|
``` |