foldsite/docs/content/develop/index.md

version, date, author, title, description, summary, quick_tips

version	date	author	title	description	summary	quick_tips
1.0	2025-01-15	DWS Foldsite Team	Develop Foldsite	Contributing to Foldsite development	Guidelines for contributing code, documentation, themes, and ideas to the Foldsite project.	Start with documentation or small bug fixes Discuss major changes in issues before implementing Follow existing code style and patterns

Develop Foldsite

Want to contribute to Foldsite? We welcome contributions of all kinds!

Ways to Contribute

1. Documentation

Impact: High | Difficulty: Low

Improving documentation helps everyone:

• Fix typos and unclear explanations
• Add missing examples
• Create tutorials
• Translate to other languages

How to start:

1. Find documentation that confused you
2. Fork the repository
3. Edit markdown files in docs/content/
4. Submit pull request

No coding required!

2. Bug Fixes

Impact: High | Difficulty: Low to Medium

Fix issues others are experiencing:

• Browse GitHub Issues
• Look for "good first issue" label
• Fix the bug
• Add test if possible
• Submit pull request

3. New Features

Impact: High | Difficulty: Medium to High

Add new capabilities:

• Discuss in issue first
• Get feedback on approach
• Implement feature
• Add documentation
• Add tests
• Submit pull request

4. Templates & Themes

Impact: Medium | Difficulty: Medium

Create reusable designs:

• Build complete theme
• Document installation
• Submit to theme gallery
• Help others customize

5. Testing

Impact: Medium | Difficulty: Low

Help ensure quality:

• Test new releases
• Report bugs with details
• Verify fixes work
• Test on different platforms

Development Setup

Prerequisites

• Python 3.10 or higher
• Git
• Text editor or IDE

Getting Started

# Clone repository
git clone https://github.com/DWSresearch/foldsite.git
cd foldsite

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt  # If exists

# Run tests
python -m pytest  # If tests exist

# Run Foldsite
python main.py --config config.toml

Development Workflow

1. Create branch for your changes:

   git checkout -b feature/my-feature
   

2. Make changes following code style

3. Test changes:

   # Manual testing
   python main.py --config config.toml
   
   # Run tests if available
   python -m pytest
   

4. Commit changes:

   git add .
   git commit -m "Add feature: description"
   

5. Push and create PR:

   git push origin feature/my-feature
   

Code Style

Python

Follow PEP 8 with these specifics:

Formatting:

• 4 spaces for indentation
• Max line length: 100 characters
• Use type hints where helpful
• Docstrings for public functions

Example:

def render_page(
    path: Path,
    base_path: Path = Path("./"),
    template_path: Path = Path("./"),
) -> str:
    """
    Renders a web page based on the provided path.

    Args:
        path: The path to the target file or directory
        base_path: The base path for relative paths
        template_path: Path to directory containing templates

    Returns:
        Rendered HTML content of the page
    """
    # Implementation...

Naming:

• snake_case for functions and variables
• PascalCase for classes
• UPPER_CASE for constants

HTML Templates

• 2 spaces for indentation
• Close all tags
• Use semantic HTML
• Comment complex logic

<article class="post">
    {% if metadata %}
        <h1>{{ metadata.title }}</h1>

        {# Loop through tags #}
        {% if metadata.tags %}
            <div class="tags">
                {% for tag in metadata.tags %}
                    <span class="tag">{{ tag }}</span>
                {% endfor %}
            </div>
        {% endif %}
    {% endif %}
</article>

CSS

• 2 spaces for indentation
• Alphabetical property order (within reason)
• Mobile-first responsive design
• BEM naming for classes (optional but encouraged)

.post {
    margin: 2rem 0;
    padding: 1rem;
}

.post__title {
    font-size: 2rem;
    font-weight: bold;
    margin-bottom: 1rem;
}

@media (min-width: 768px) {
    .post {
        margin: 3rem 0;
        padding: 2rem;
    }
}

Architecture Overview

Key Components

main.py

• Entry point
• Initializes configuration
• Registers template helpers
• Starts server

src/config/

• Configuration loading
• Command-line argument parsing

src/server/

• Flask application setup
• Route registration
• File manager (admin interface)

src/routes/

• URL routing logic
• Path validation and security
• Content serving

src/rendering/

• Template discovery
• Markdown rendering
• Page rendering pipeline
• Helper functions

Request Flow

1. HTTP Request
   ↓
2. Flask routes (/src/routes/routes.py)
   ↓
3. Path validation & security checks
   ↓
4. Template discovery (/src/rendering/template_discovery.py)
   ↓
5. Content rendering (/src/rendering/renderer.py)
   ↓
6. Template rendering with Jinja2
   ↓
7. HTTP Response

Adding a New Template Helper

Template helpers are functions available in all templates.

1. Add to TemplateHelpers class (src/rendering/helpers.py):

class TemplateHelpers:
    def __init__(self, config: Configuration):
        self.config = config

    def get_my_helper(self, param: str) -> list:
        """
        Description of what this helper does.

        Args:
            param: Description of parameter

        Returns:
            Description of return value
        """
        # Implementation
        result = []
        # ... logic ...
        return result

2. Register in main.py:

server.register_template_function("get_my_helper", t.get_my_helper)

3. Use in templates:

{% for item in get_my_helper('value') %}
    {{ item }}
{% endfor %}

4. Document in docs/content/templates/template-helpers.md

Testing

Manual Testing

Create test content:

test-site/
├── content/
│   ├── index.md
│   ├── test-post.md
│   └── photos/
│       └── test.jpg
├── templates/
│   ├── base.html
│   └── __file.md.html
└── styles/
    └── base.css

Run and verify:

python main.py --config test-config.toml

Writing Tests

Note: Test infrastructure may need to be set up

Example test structure:

# tests/test_renderer.py
import pytest
from pathlib import Path
from src.rendering.renderer import render_page

def test_render_simple_markdown():
    """Test rendering a basic markdown file"""
    # Setup
    content = Path("test-content/simple.md")
    templates = Path("test-templates")

    # Execute
    result = render_page(content, template_path=templates)

    # Assert
    assert "<h1>" in result
    assert "<!DOCTYPE html>" in result

Pull Request Guidelines

Before Submitting

• Code follows style guidelines
• Changes are focused (one feature/fix per PR)
• Commit messages are clear
• Documentation updated if needed
• Manual testing completed
• No merge conflicts

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Refactoring
- [ ] Other (describe)

## Testing
How you tested the changes

## Screenshots
If UI changes, add screenshots

## Checklist
- [ ] Code follows project style
- [ ] Self-reviewed code
- [ ] Commented complex code
- [ ] Updated documentation
- [ ] No breaking changes (or documented)

Review Process

1. Maintainer reviews code and design
2. Feedback provided if changes needed
3. Discussion on approach if necessary
4. Approval when ready
5. Merge by maintainer

Be patient - maintainers are volunteers.

Issue Guidelines

Bug Reports

Use this template:

**Foldsite Version:** X.X.X
**Python Version:** X.X.X
**OS:** macOS/Linux/Windows

**Description:**
Clear description of the bug

**Steps to Reproduce:**
1. Step one
2. Step two
3. See error

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Error Messages:**

Paste full error/traceback

**Additional Context:**
Any other relevant information

Feature Requests

Use this template:

**Feature Description:**
Clear description of the feature

**Use Case:**
Why you need this feature

**Proposed Implementation:**
Ideas for how it could work (optional)

**Alternatives Considered:**
Other solutions you've thought about

**Additional Context:**
Examples, mockups, etc.

Communication

GitHub Issues

• Bugs - Report problems
• Features - Request improvements
• Questions - Ask for help (or use Discussions)

GitHub Discussions

• Q&A - Get help using Foldsite
• Ideas - Discuss potential features
• Show and Tell - Share what you built
• General - Everything else

Response Times

• Critical bugs - Few days
• Other issues - 1-2 weeks
• Feature requests - Varies
• PRs - 1-2 weeks

Security

Reporting Vulnerabilities

Do not open public issues for security problems.

Email: security@dws.rip

Include:

• Description of vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if you have one)

Security Considerations

When contributing:

• Validate all file paths
• Sanitize user inputs
• Be careful with path traversal
• Don't expose sensitive info in errors
• Follow principle of least privilege

Project Philosophy

Keep these in mind when contributing:

1. Simplicity

Prefer simple solutions over complex ones. Add complexity only when necessary.

2. Convention Over Configuration

Sensible defaults that work for most cases. Configuration for edge cases.

3. User Focus

Optimize for content creators, not developers. Make common tasks easy.

4. Clear Over Clever

Code should be understandable. Clever tricks make maintenance harder.

5. Backward Compatibility

Don't break existing sites without very good reason and clear migration path.

Resources

Learning

• Python - docs.python.org
• Flask - flask.palletsprojects.com
• Jinja2 - jinja.palletsprojects.com

Tools

• VS Code - Great Python support with extensions
• PyCharm - Full-featured Python IDE
• Git - Version control
• GitHub CLI - Command-line GitHub interface

Recognition

Contributors are recognized:

• README - Listed in contributors section
• Release notes - Mentioned in changelogs
• Commits - Your name in git history
• Gratitude - Appreciation from the community!

Getting Help

Stuck on contribution?

• Read existing code - Learn from examples
• Ask in Discussions - Community can help
• Open draft PR - Get early feedback
• Reach out - DWS team is friendly!

Next Steps

• Browse issues - Find something to work on
• Read the code - Understand how it works
• Make a change - Start small
• Submit PR - Share your contribution!

Thank you for helping make Foldsite better!

Remember: Every contribution matters, from fixing a typo to adding major features. We appreciate all help!