New to websites? Publish your first site using GitHub in your browser. You do not need to install anything on your computer.
Moving an existing site? Follow the migration guide and checklist.
Browse documentation topics for tagged guides and references. Topic coverage is partial; the sections below list all documentation.
Tutorials
Follow a guided path to your first result.
- Publish your first site: create a blog, change its title and publish an edited article.
- Publish an illustrated page: continue with your published starter blog, create a photo page and link it from the menu.
How-To Guides
Choose a task for a site you already have. Basic changes come first; search and comments are optional.
- Change your site’s name and author.
- Create a post or a page.
- Display an article date in another language.
- Add a table of contents inside an article.
- Add an alert box, an image caption or a footnote.
- Add a Font Awesome icon.
- Add tag and category indexes.
- Add an image or a photo gallery.
- Add a manual slideshow or enable PhotoSwipe.
- Embed a video or add a Mermaid diagram.
- Choose a skin or change one color.
- Add a favicon or use the bundled font.
- Change fonts or code highlighting.
- Enable Autothemer or adapt a Sass skin.
- Add or change a menu link.
- Edit footer links.
- Migrate from another theme.
- Run and publish a starter example: for readers who already use Jekyll.
- Enable local search with Fuse.js, Lunr.js or Simple-Jekyll-Search.
- Connect Google Custom Search or Algolia and its index upload.
- Connect comments: giscus, Disqus, Cactus or Welcomments.
- Reconnect an existing self-hosted Cusdis service: archived upstream; not a new hosted setup.
- Enable GoatCounter or Google Analytics 4.
- Set a post’s sharing text and images or control a page’s search visibility.
- Point a republished article to its original URL.
- Identify a personal site’s publisher.
- Check accessibility and performance.
- Find missing changes or fix a YAML error.
- Publish posts in feeds or keep an existing jekyll-feed address.
- Check your theme version.
- Add custom HTML to the head.
- More questions and formatting examples.
- Install a remote theme or the theme gem on an existing Jekyll site.
Reference
Look up an option, supported value, default or constraint. The references include configuration examples and links to related task guides.
- Global settings: site identity, navigation, integrations and build settings.
- Layouts, snippets and advanced page settings.
- Migration field mappings: legacy patterns, integration fields and release constraints.
- Accessibility and resource loading: expected behavior, version limits and offline/review scope.
- Custom hooks: supported files, insertion points and override constraints.
- Theme variables and the variables dictionary.
- Starter examples: source files, annotated demos and limitations.
- Markdown cheatsheet.
- Syntax highlighting examples.
Explanation
- How publishing fits together: understand source files, builds and the public site.
- How skins and overrides interact: understand why an existing color or font can remain in effect.