docs refactor
All checks were successful
All checks were successful
This commit is contained in:
314
docs/content/theme-gallery.md
Normal file
314
docs/content/theme-gallery.md
Normal file
@ -0,0 +1,314 @@
|
||||
---
|
||||
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!*
|
||||
Reference in New Issue
Block a user