--- version: "1.0" date: "2025-01-15" author: "DWS Foldsite Team" title: "Theme Gallery" description: "Download and use community-created Foldsite themes" summary: "Browse ready-to-use themes for Foldsite. Download complete template and style packages to jumpstart your site." quick_tips: - "Themes are complete template + style packages you can drop into your project" - "All themes are free and open source" - "Customize themes to make them your own" --- # Theme Gallery Ready-to-use themes for Foldsite. Download, customize, and launch your site quickly. ## What is a Theme? A Foldsite theme is a complete package of: - **Templates** (`templates/` directory) - **Styles** (`styles/` directory) - **Example content** (optional) - **Configuration** (optional) Simply download and drop into your Foldsite project. ## Official Themes ### Default Theme **Included in:** Foldsite repository (`example_site/`) **Type:** Blog + Gallery **Best for:** Personal sites, blogs with photos **Features:** - Responsive sidebar navigation - Blog post support with metadata - Photo gallery views - Breadcrumb navigation - Clean, minimal design **Install:** ```bash # Copy from example_site cp -r example_site/template my-site/templates cp -r example_site/style my-site/styles ``` **Preview:** See [Tanishq Dubey's site](https://tanishq.page) --- ### Documentation Theme **Included in:** Foldsite repository (`docs/`) **Type:** Documentation **Best for:** Project docs, technical writing, knowledge bases **Features:** - Hierarchical navigation - Sibling page links - Code syntax highlighting - Breadcrumb trails - Clean, readable typography **Install:** ```bash # Copy from docs cp -r docs/templates my-site/templates cp -r docs/styles my-site/styles ``` **Preview:** This documentation site! --- ## Community Themes *Community-contributed themes will appear here as they're created and submitted.* ### How to Submit a Theme Created a theme you want to share? **Requirements:** - Complete templates and styles - README with installation instructions - Screenshot or demo site - MIT or similar permissive license - No external dependencies (except common CDNs) **Submission process:** 1. Create GitHub repository with your theme 2. Open issue on Foldsite repo with "Theme Submission" label 3. Include: - Theme name and description - Screenshot or demo URL - Repository link - What makes it unique 4. We'll review and add to gallery **Theme structure:** ``` my-theme/ ├── README.md ├── LICENSE ├── templates/ │ ├── base.html │ ├── __file.md.html │ └── ... ├── styles/ │ ├── base.css │ └── ... ├── screenshots/ │ └── preview.png └── example-content/ (optional) └── ... ``` --- ## Using a Theme ### Installation 1. **Download theme** (clone or download ZIP) 2. **Copy to your project:** ```bash cp -r theme-name/templates my-site/templates cp -r theme-name/styles my-site/styles ``` 3. **Configure paths** in `config.toml`: ```toml [paths] templates_dir = "/path/to/my-site/templates" styles_dir = "/path/to/my-site/styles" ``` 4. **Test:** ```bash python main.py --config config.toml ``` ### Customization Themes are starting points. Make them your own! **Easy customizations:** - Change colors in CSS - Modify fonts - Adjust spacing and sizing - Replace logo/branding - Update footer text **Advanced customizations:** - Modify templates - Add new template variants - Change layout structure - Add custom helper functions - Integrate JavaScript libraries **Best practice:** Keep original theme in git so you can track your changes. --- ## Theme Development Want to create your own theme? ### Theme Checklist A complete theme should include: **Required Templates:** - [ ] `base.html` - Main page wrapper - [ ] `__file.md.html` - Markdown file display - [ ] `__folder.md.html` - Folder index for documents - [ ] `__error.html` - Error pages **Optional but Recommended:** - [ ] `index.html` - Custom homepage - [ ] `__folder.image.html` - Photo galleries - [ ] `__file.document.html` - Document-specific layout **Styles:** - [ ] `base.css` - Base styles, always loaded - [ ] `__file.md.css` - Markdown file styles - [ ] `__folder.image.css` - Gallery styles - [ ] Responsive design (mobile-friendly) **Documentation:** - [ ] README with installation instructions - [ ] Screenshot or demo - [ ] List of features - [ ] Customization guide - [ ] License (MIT recommended) ### Design Guidelines **For consistency and usability:** 1. **Mobile-first** - Design for small screens first 2. **Accessible** - Follow WCAG guidelines 3. **Fast** - Minimize CSS, optimize images 4. **Semantic HTML** - Use proper elements 5. **Print-friendly** - Consider print stylesheets **Typography:** - Readable font sizes (16px+ for body) - Good line height (1.5+) - Proper contrast ratios - System fonts or fast-loading web fonts **Colors:** - Consistent color palette - Sufficient contrast - Dark mode consideration (optional) **Layout:** - Clear visual hierarchy - Consistent spacing - Responsive breakpoints - Touch-friendly (44px+ tap targets) ### Testing Your Theme Before sharing, test with: - **Various content types** - Markdown, images, mixed - **Different structures** - Flat vs. deep hierarchies - **Edge cases** - Long titles, no metadata, many tags - **Devices** - Mobile, tablet, desktop - **Browsers** - Chrome, Firefox, Safari ### Inspiration Look at themes from other static site generators: - Jekyll themes - Hugo themes - 11ty themes - Gatsby themes Adapt patterns (don't copy code) to Foldsite's template system. --- ## Coming Soon **Future theme additions:** - **Minimal Blog** - Ultra-simple, typography-focused - **Photo Portfolio** - Full-screen galleries, minimal UI - **Magazine** - Multi-column, content-rich - **Landing Page** - Single-page, marketing-focused - **Academic** - Papers, publications, research-focused Want to help create these? See [Develop Foldsite](develop/). --- ## Theme Showcase *Once community themes are available, this section will showcase screenshots and live demos.* --- ## Frequently Asked Questions **Q: Are themes free?** A: Yes! All themes in the official gallery are free and open source. **Q: Can I sell themes I create?** A: The themes themselves must be open source if listed here, but you could offer customization services commercially. **Q: Do themes work with all Foldsite versions?** A: Themes should specify compatible versions. Most work across versions unless core template system changes. **Q: Can I request a specific theme?** A: Open an issue with "Theme Request" label. No guarantees, but community might help! **Q: How do I update a theme?** A: If you've customized it, manually merge changes. Otherwise, re-download and replace. **Q: Can I mix themes?** A: Yes! Take templates from different themes. Just ensure styles don't conflict. --- ## Contributing Help grow the theme ecosystem: - **Create themes** - Share your designs - **Improve docs** - Help others use themes - **Test themes** - Report issues - **Showcase sites** - Inspire others See [Develop Foldsite](develop/) for contribution guidelines. --- ## Support Need help with themes? - **[Support](support.md)** - Get help - **[Templates Guide](templates/)** - Learn the system - **[Recipes](recipes/)** - See examples - **GitHub Issues** - Report theme bugs --- *This gallery is just getting started. As the Foldsite community grows, expect many more themes! Consider contributing the first one!*