315 lines
7.5 KiB
Markdown
315 lines
7.5 KiB
Markdown
---
|
|
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!*
|