foldsite/docs/content/theme-gallery.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	Theme Gallery	Download and use community-created Foldsite themes	Browse ready-to-use themes for Foldsite. Download complete template and style packages to jumpstart your site.	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:

# 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

---

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:

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

   cp -r theme-name/templates my-site/templates
   cp -r theme-name/styles my-site/styles
   

3. Configure paths in config.toml:

   [paths]
   templates_dir = "/path/to/my-site/templates"
   styles_dir = "/path/to/my-site/styles"
   

4. Test:

   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.

---

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 for contribution guidelines.

---

Support

Need help with themes?

• Support - Get help
• Templates Guide - Learn the system
• 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!