Aista Jekyll Theme

Aista Jekyll Theme is a content-first Jekyll documentation theme created by Aista Ltd for their Magic Cloud framework and released under Creative Commons Attribution-ShareAlike 4.0. It turns a standard Jekyll project into a documentation site with a blog, custom navigation, and configurable branding, deployable on GitHub Pages via a remote theme.

What is Aista Jekyll Theme?

The Aista Jekyll Theme is a remote Jekyll theme designed for documentation-heavy sites, originally built to document Magic Cloud. It takes Markdown files and YAML configuration as input and produces a static website with blog listing, dropdown navigation, and custom pages. The theme runs on any Jekyll installation and is designed for GitHub Pages remote-theme deployment through the remote_theme setting. It is open-sourced by Aista Ltd under Creative Commons Attribution-ShareAlike 4.0.

Key Features

• Remote theme installation — Declare remote_theme: polterguy/aista-jekyll in your _config.yml to use the theme on GitHub Pages with no local build step.
• Content-first layouts — Provides default, blog, and post layouts that keep content prominent, with minimal chrome around it.
• Blog support — Save posts in the _posts folder and create a blog.md page with layout: blog to automatically list them at /blog/.
• Configurable navigation — Define nested dropdown menu items under nav_sections in YAML; they render as a hamburger-toggled navbar.
• Most Wanted Response (MWR) — Highlight a single primary link using mwr and mwr_text; the element is skipped if you don't set it.
• Google Analytics — Add your tracking ID via the google_analytics YAML option for visitor analytics.
• Open Graph image — Set og_image to control the thumbnail shown when pages are shared on social platforms.
• Custom backgrounds — Configure banner_bg and body_bg image paths for the banner and body background.

Who is it for?

• Open-source project maintainers — Document a framework or library with a content-oriented site, as Aista does for Magic Cloud.
• Technical writers and documentation teams — Publish and organize docs and blog posts using plain Markdown with minimal front matter.
• GitHub Pages users — Deploy a documentation site on GitHub Pages without a local build pipeline by using the remote-theme mechanism.

What can you do with it?

• Project documentation: Create dedicated doc pages with custom permalinks and a nested navigation menu that works on mobile via a hamburger toggle.
• Blog publishing: Add dated posts in _posts, then link to a blog listing page that shows all posts automatically.
• Branded site setup: Customize the headline, slogan, copyright text, background images, and Open Graph image directly from _config.yml.

How does it work?

To use the theme, add remote_theme: polterguy/aista-jekyll to your _config.yml and configure the optional settings shown in the README. Push the repository to GitHub Pages, and the theme is applied automatically. Blog posts are created as Markdown files in _posts with the post layout, while custom pages use the default layout and a permalink in front matter.

Pros and cons

• Pros: Open source and free; simple YAML configuration; designed for documentation; works directly with GitHub Pages; blog-aware.
• Cons: The Creative Commons Attribution-ShareAlike 4.0 license requires keeping a link to Aista's website on any site using the theme.

Pricing

The theme is free to use under the Creative Commons Attribution-ShareAlike 4.0 license, with no paid tiers or premium features mentioned.

FAQ

Is the Aista Jekyll theme free to use?

Yes, the theme is open source under Creative Commons Attribution-ShareAlike 4.0. You may use it for any site, but you must keep a link to Aista's website and share derivative works under the same license.

Does the theme work on GitHub Pages?

Yes, it was explicitly created for GitHub Pages. You use the remote_theme setting in _config.yml to apply it without cloning or building the theme locally.

How do I add navigation sections to the theme?

Add a nav_sections list in _config.yml with each section's name and an items list containing URLs and names. These appear in a hamburger menu at the top of the page, and the menu is omitted if you don't define it.

How do I create a blog post?

Create a Markdown file in the _posts folder with a date-prefixed filename, and set layout: post in the front matter. To list posts, create a page with layout: blog and a permalink like /blog/.