foldsite/docs/content/develop/index.md

---
version: "1.0"
date: "2025-01-15"
author: "DWS Foldsite Team"
title: "Develop Foldsite"
description: "Contributing to Foldsite development"
summary: "Guidelines for contributing code, documentation, themes, and ideas to the Foldsite project."
quick_tips:
  - "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](https://github.com/DWSresearch/foldsite/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

```bash
# 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:
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Make changes** following code style

3. **Test changes**:
   ```bash
   # Manual testing
   python main.py --config config.toml

   # Run tests if available
   python -m pytest
   ```

4. **Commit changes**:
   ```bash
   git add .
   git commit -m "Add feature: description"
   ```

5. **Push and create PR**:
   ```bash
   git push origin feature/my-feature
   ```

## Code Style

### Python

Follow [PEP 8](https://pep8.org/) with these specifics:

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

**Example:**

```python
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

```html
<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)

```css
.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`):

```python
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**:

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

**3. Use in templates**:

```jinja
{% 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:
```bash
python main.py --config test-config.toml
```

### Writing Tests

*Note: Test infrastructure may need to be set up*

Example test structure:

```python
# 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

```markdown
## 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:

```markdown
**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:

```markdown
**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](https://docs.python.org/)
- **Flask** - [flask.palletsprojects.com](https://flask.palletsprojects.com/)
- **Jinja2** - [jinja.palletsprojects.com](https://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!