Get AsciiDocsy!
If you are looking for a full-featured theme to dress a Jekyll application with content sourced in AsciiDoc, consider taking the AsciiDocsy journey with us.
OR
AsciiDocsy is an Asciidoctor-ready Jekyll theme for technical documentation, adaptable to pretty much any Jekyll application.
This page is NOT part of the AsciiDocsy theme. It is merely the version 0.1.0-alpha landing page. |
If you are looking for a full-featured theme for a Jekyll application with content sourced in AsciiDoc, consider taking the AsciiDocsy journey with us.
AsciiDocsy is designed by a technical documentation specialist who builds bespoke AsciiDoc platforms for world-class enterprises.
On the front end, AsciiDocsy delivers. Designed to meet the technical documentation deployment needs of full-scale, multi-product software companies, AsciiDocsy remains fully aware that all such enterprises start small and still need world-class docs.
On the back end, AsciiDocsy unifies. The codebase brings together developers and technical writers, allowing the latter to achieve momentous feats in collaboration with the developers whose work they document.
You have (or will have) lots of criss-crossing links navigating a complex site structure.
Organize them sensibly with AsciiDocsy.
YAML-sourced Navgoco menu for nested and grouped links.
Automatically generated, with elegant, context-aware nesting and spyscroll.
Simple, horizontal site navigation with sublinks, fully configurable with YAML.
Equipped with jekyll-asciidoc plugin gem, the core Asciidoctor style sheet alternate skins, a starter PDF theme, Asciidoctor extensions lab, and much more.
Inline semantics with custom CSS styles — use AsciiDocsy’s or make your own.
Pick from classic DocBook/AsciiDoc admonitions and some AsciiDocsy originals.
Take advantage of AsciiDoc includes, variables (“attributes”), and conditionals and treat your docs like the application they need to be.
Skill Level
Built mostly with Liquid and jQuery, AsciiDocsy is aimed at docset maintainers with some support from a junior developer.
|
We have chosen our our dependencies carefully, aiming for popularity and relative simplicity. There are no heavy-duty frameworks that orchestrate the entire frontend; just tried-and-true libraries that play nice together.
Google’s premiere JavaScript framework, jQuery provides enormous power over the browser.
Twitter’s HTML/CSS/JS library, built largely on jQuery, provides a foundation of convenient code covering a staggering range of Web 2.0 needs, with most of the kinks worked out.
Easily swappable for another icon system, FontAwesome is an old favorite that never seems to get old.
We listened to what technical teams want in their documentation sites, and we coded it into AsciiDocsy. We define all these features in YAML, configuring or toggling them off all in one place without modifying the templates.
Edit or create links for topics and pages.
The classic, “Was this page useful?”
For compliance with European Internet privacy laws, a discrete message notifying the user that you only use cookies to help them navigate the site (which AsciiDocsy does).
I mean, you do not, in fact, track them in any other way while they’re just trying to use your documentation, right? You can be as creepy as you want with this theme, but maybe don’t.
While GitHub Pages does not permit the jekyll-asciidoc plugin, a deployment chain from GitHub or Gitlab to a hosting platform like Netlify or Vercel is a great option.
Then set up your CI/CD operations either at your Git host, your existing CI/CD platform, or your deployment host.
For turnkey static-site deployments, including staging sites for review and automatic integration with your repos on GitLab, Bitbucket, or GitHub, you can’t go wrong with Netlify.
Search can get expensive with tons of content and heavy traffic, but at the lower tiers it is quite affordable even to most startups. Algolia offers great Jekyll integration, and we’ve assembled a useful frontend for search fields and search results.