markItDown
📱 A React app to preview and edit Markdown✍. You can also export it as HTML.
JavaScript★ 51
al-folio
A beautiful, simple, clean, and responsive Jekyll theme for academics
alshedivatHTML★ 16k⑂ 13k forksMITupdated 1 day ago
README.mdfork it — it’s yours
al-folio
A simple, clean, and responsive Jekyll starter for academic websites.
In v1.x, al-folio is a thin starter, not a theme: the runtime ships as independently versioned plugin gems, so you pick up fixes and features by bumping a pinned version in your Gemfile instead of merging theme internals into your site.
Getting started
⚠️ Important: Use "Use this template" (not fork)
When creating your own website with al-folio, you have two options:
- ✅ Recommended: Click "Use this template" – This creates a clean copy that is independent from the main al-folio repository. Changes you make to your site won't be accidentally submitted to al-folio as pull requests.
- ❌ Not recommended: Forking the repository – This keeps a link to the main al-folio repo, making it easy to accidentally submit your personal site changes as contributions to our project.
If you already forked: Don't worry! You can still work with your fork normally. Just make sure to:
- Make changes on a dedicated branch (e.g.,
my-site-updates) - When pushing changes, always verify you're pushing to your own repository, not the main al-folio repository
- Never create pull requests to
alshedivat/al-foliounless you're intentionally contributing improvements that benefit all users
For quick setup, see docs/QUICKSTART.md.
Want to learn more about Jekyll? Check out this tutorial. Why Jekyll? Read Andrej Karpathy's blog post! Why write a blog? Read Rachel Thomas blog post.
Table Of Contents
- al-folio
Installing and Deploying
For installation and deployment details please refer to docs/INSTALL.md.
Customizing
For customization details please refer to docs/CUSTOMIZE.md.
Plugin Ecosystem
al-folio is a thin starter in v1.x. Runtime features are plugin-owned and published as Ruby gems.
- Ownership boundaries: docs/BOUNDARIES.md
- Plugin catalog metadata:
_data/featured_plugins.yml - Rendered plugin catalog: alshedivat.github.io/al-folio/plugins/
- Plugin catalog page source:
_pages/plugins.md
The catalog page is deliberately kept out of the navbar (nav: false) so the demo site's chrome stays unchanged; reach it through the links above.
Naming convention:
- Theme-coupled plugins use
al-folio-<feature>repos andal_folio_<feature>gem/plugin ids. - Reusable plugins can use
al-<feature>or neutral naming.
Featured plugins and bundled starter plugins are different tracks. Bundling requires explicit updates to Gemfile and _config.yml.
Plugin-owned changes should be made in the owning al-org-dev plugin repository, not by copying runtime assets into this starter.
The bundled v1 plugin repos are:
al-folio-core: shared layouts, includes, style/runtime primitives, and upgrade contractsal-folio-cv: CV renderingal-folio-distill: Distill layouts and runtime assetsal-folio-bootstrap-compat: temporary Bootstrap compatibility runtimeal-folio-upgrade: v1 upgrade audit/report/codemodsal-icons: icon loadingal-search: search runtimeal-citations: publication/citation helpersal-ext-posts: external post ingestional-analytics,al-comments,al-cookie,al-img-tools,al-math,al-charts, andal-newsletter: feature-specific runtime and integration behavior
Using AI Agents
al-folio v1.x is designed for agent-assisted setup and migration. Agents should read AGENTS.md first, then use docs/BOUNDARIES.md to route changes to the starter or the owning plugin repo.
For existing customized forks, the recommended migration path is to ask an agent to use the al-folio v1 migration skill. The skill walks through creating a disposable migration branch, bringing site-owned content/config/data onto the v1 starter contract, running al_folio_upgrade, auditing local overrides, and validating the build. This is preferred over a manual file-by-file upgrade because v1 runtime ownership moved into plugins and local overrides need explicit drift tracking.
The canonical skills live in .agents/skills/. They are also exposed through .codex/skills/ and .claude/skills/ symlinks for agents that discover skills from tool-specific directories.
Codex
Codex can use the repo-local skills:
- al-folio bootstrap: create and configure a new v1 site.
- al-folio v1 migration: migrate customized forks and audit local overrides.
Useful first prompts:
- "Use the al-folio bootstrap skill to configure my new site."
- "Use the al-folio v1 migration skill to migrate this customized fork and run the override audit."
Claude
Claude should start from CLAUDE.md, which imports AGENTS.md. For setup or migration tasks, use the matching skill from .claude/skills/, which points to the canonical .agents/skills/ directory.
Copilot And Other Agents
Copilot should follow .github/copilot-instructions.md and the specialized agents in .github/agents/. Other agents should follow the same rule: keep starter work in this repo, route runtime behavior to the owning al-org-dev plugin, and run bundle exec al-folio upgrade overrides audit whenever local overrides are added or retained.
Documentation
Comprehensive guides for all aspects of your al-folio website:
- Documentation index – All user, maintainer, and migration guides
- Quick Start – Get running in 5 minutes
- Installation & Deployment – Set up your site on GitHub Pages or other platforms
- Customization Guide – Personalize your website (CVs, publications, themes, etc.)
- Troubleshooting – Fix common issues (deployment, build, styling, content)
- FAQ – Frequently asked questions and solutions
- Analytics – Add website analytics and visitor tracking
- SEO Guide – Optimize for search engines and improve discoverability
- Plugin Catalog – Featured and bundled plugin metadata (page source)
Features
Light/Dark Mode
This template has a built-in light/dark mode. It detects the user preferred color scheme and automatically switches to it. You can also manually switch between light and dark mode by clicking on the sun/moon icon in the top right corner of the page.
CV
Your CV can be generated in one of two modern formats: RenderCV (recommended, with automatic PDF generation) or JSONResume (standardized JSON format). You can use both simultaneously and switch between them, or maintain just the one you prefer.
For setup and customization details, see Modifying the CV information in docs/CUSTOMIZE.md.
People
You can create a people page if you want to feature more than one person. Each person can have its own short bio, profile picture, and you can also set if every person will appear at the same or opposite sides.
Publications
Your publications page is generated automatically from your BibTeX bibliography. You can customize publication display, add extra information like PDFs, and control sorting behavior.
For setup, BibTeX field documentation, and customization options, see Adding a new publication and Managing publication display in docs/CUSTOMIZE.md.
Collections
al-folio uses Jekyll collections to organize content into categories. The starter comes with four default collections — news, projects, books, and teachings — all declared under collections: in _config.yml. You can easily create your own collections for apps, stories, courses, or any other creative work.
For detailed instructions on creating and customizing collections, see Adding Collections in docs/CUSTOMIZE.md.
Layouts
al-folio comes with stylish layouts for pages and blog posts.
The iconic style of Distill
The theme allows you to create blog posts in the distill.pub style:
For more details on how to create distill-styled posts using <d-*> tags, please refer to the example.
Full support for math & code
al-folio supports fast math typesetting through MathJax and code syntax highlighting using GitHub style. Also supports chartjs charts, mermaid diagrams, and TikZ figures.
Photos, Audio, Video and more
Photo formatting is made simple using Tailwind-first responsive layout utilities. Easily create beautiful grids within your blog posts and project pages, also with support for video and audio embeds:
Other features
GitHub's repositories and user stats
al-folio displays GitHub repositories and user stats on the /repositories/ page using github-stats-extended and github-profile-trophy.
To configure which repositories and GitHub profiles to display, see Modifying the user and repository information in docs/CUSTOMIZE.md.
Theming
al-folio offers a variety of beautiful theme colors to choose from. The default is purple, but you can customize colors, fonts, spacing, and more to match your style.
For detailed customization instructions, see Changing theme color and Customizing fonts, spacing, and more in docs/CUSTOMIZE.md.
Social media previews
al-folio supports Open Graph preview images on social media. When enabled, your site's pages display rich preview objects with images, titles, and descriptions when shared.
For setup and customization, see Social media previews in docs/CUSTOMIZE.md.
Atom (RSS-like) Feed
It generates an Atom (RSS-like) feed of your posts, useful for Atom and RSS readers. The feed is reachable simply by typing after your homepage /feed.xml. E.g. assuming your website mountpoint is the main folder, you can type yourusername.github.io/feed.xml
Related posts
By default, blog posts display related posts at the bottom. These are selected by finding the most recent posts that share tags with the current post. You can customize this behavior on a per-post or site-wide basis.
For configuration details, see Related posts in docs/CUSTOMIZE.md.
Code quality checks
Currently, we run some checks to ensure that the code quality and generated site are good. The checks are done using GitHub Actions and the following tools:
- Prettier - check if the formatting of the code follows the style guide
- lychee - check for broken links
- Axe (need to run manually) - do some accessibility testing
We decided to keep Axe runs manual because fixing the issues are not straightforward and might be hard for people without web development knowledge.
GDPR Cookie Consent Dialog
al-folio includes a GDPR-compliant cookie consent dialog provided by the al_cookie plugin to ensure your website respects visitor privacy. The dialog is powered by Vanilla Cookie Consent and integrates seamlessly with all supported analytics providers.
When enabled, analytics scripts are blocked until the user explicitly consents, and user preferences are saved across visits. This is essential for websites serving visitors in the European Union and other regions with strict privacy regulations.
For complete setup and customization details, see GDPR Cookie Consent Dialog in docs/CUSTOMIZE.md.
User community
Academics around the world use al-folio for their homepages, blogs, and lab pages, as well as webpages for courses, workshops, conferences, meetups, and more.
Want your site listed? Post a request in the Showcase category of GitHub Discussions — we review and add entries periodically. Please do not open a pull request for this.
Lighthouse PageSpeed Insights
Desktop
Run the test yourself: Google Lighthouse PageSpeed Insights
Mobile
Run the test yourself: Google Lighthouse PageSpeed Insights
FAQ
For frequently asked questions, please refer to docs/FAQ.md.
Contributing
Contributions to al-folio are very welcome! Before you get started, please take a look at the guidelines.
If you would like to improve documentation or fix a minor inconsistency or bug, please feel free to send a PR directly to main. For more complex issues/bugs or feature requests, please open an issue using the appropriate template.
Maintainers
Our most active contributors are welcome to join the maintainers team. If you are interested, please reach out!
 Maruan |
 Rohan Deb Sarkar |
 Amir Pourmand |
 George |
All Contributors
Star History
Generated by bin/generate_star_history.py and refreshed automatically by star-history.yml.
License
al-folio is available as open source under the terms of the MIT License.
Originally, al-folio was based on the *folio theme (published by Lia Bogoev and under the MIT license). Since then, it got a full re-write of the styles and many additional cool features.
more like this