docops / asciidocsy-jekyll-theme Goto Github PK
View Code? Open in Web Editor NEWJekyll/AsciiDoc port of Docsy theme for scalable technical documentation projects
Home Page: https://asciidocsy.netlify.app/docs
License: Apache License 2.0
Jekyll/AsciiDoc port of Docsy theme for scalable technical documentation projects
Home Page: https://asciidocsy.netlify.app/docs
License: Apache License 2.0
Cross-references are a big problem in most static-based websites, and this is not resolved by adding AsciiDoc to the mix, even though AsciIDoc has xrefs built in. At the time of conversion, each page is treated like a distinct document, and Asciidoctor does not know what other documents are, let alone where they are.
This is the reason to use a manifest that generates menus and also records some metadata for each topic, so there is a central dataset that understands the information architecture and knows all the paths.
To render hyperlinked cross-references (xrefs)in this theme (or any jekyll-asciidoc-driven site), we use syntax like <</path/to/topic#,Topic Title or Other Text Here>>
. This means we must know the exact URL of the resource and its title, and if those change, we'll have to search-and-replace to catch xrefs.
Alternatively, we could pre-generate a big set of xrefs and store them and make them available as AsciIDoc attributes (variables). For example, <<{xref_topic-slug-here}>>
could render an xref just like the previous, conventional syntax. Or use <<{xref_topic-slug-here_notitle},some arbitrary text>>
if you don't want to render the title of the referenced toipic.
That is the simple part. The hard part is loading them for each document build. Every document build ingests AsciiDoc attributes from site.asciidoctor.attributes
, but those are sourced as static YAML files that won't exist at the top of the build when they're required.
Alternatively, we can generate an attributes.adoc
file (using a Jekyll include), and then we can embed that at the top of each topic as an AsciiDoc include (I think?), but in this case we would need a reference this include in any file that uses the xref variables. I don't think there's a way to use layouts or any other global feature to ingest the attributes on a per-topic basis.
The only other option I can think of at this time is to create a plugin that preprocesses the manifest into a list of AsciiDoc attributes and ingests it. This might be optimal, and then it would apply to any theme that wanted to use it, right out of the box.
I've run into this issue before, and I'm also sure this was working previously in the theme. It's supposed to be pretty simple: turn on the :experimental:
and use the macro.
I don't understand why it sometimes fails and Google is silent.
This library is awesome. There are lots of cases for giving users the ability to easily rearrange tables and lists.
Handlers with buttons cannot display their text/icon labels. The labels should be similar to those for selectboxes, but I wasn't immediately able to do that in #48 so I punted.
I initially thought the idea of putting most theme-defining data objects in the site
scope -- meaning defined in one or more config files -- made a lot of sense, just to have an elegant structure and not use the _data/
dir for theme-defining stuff.
Now I think it's just annoying and too restrictive. Since there is no way to declare multiple config files from within a config file (you have to use the CLI's --config folder/file-one.yml,folder/file-two.yml,etc
argument), it's not easy to break up the config file without adding lots of noise to the commandline. This can easily be remedied by the techniques most shops employ in their build routines, where long CLI commands don't matter, but I want AsciiDocsy to be a good authoring experience right out of the box, which means keeping CLI commands as simple as possible.
This leaves us with the option of moving some or all of these to the _data/config/
path, which for the AsciiDocsy site itself is _docs/_data/theme/
-- another part of the reason I like keeping this out of the data path. But I do think this is the best move. This gives the user complete control over which objects to store together. Even though you have to maintain the hierarchy/tree, with Jekyll's data
scope, we have the option to store EVERYTHING in a _data/theme.yml
file or split things up into _data/config/navigation.yml
or even _data/config/navigation/breadcrumbs.yml
and so forth.
So now site.features
will be site.data.theme.features
.
Except I think I also want to get rid of the extra tiers in the features
object, starting with eliminating the category features itself. The actions
block is probably also superfluous. If we flatten the objects down, we need no _data/config/features/
path, let alone _data/config/features/actions/
.
Hello,
I apologize in advance because this ticket isn't related to an issue, but rather a question about the usage of the theme. I got acquainted with Jekyll and "Documentation Theme" developed by Tom Johnson. But I wanted to make it compliant with AsciiDoc instead of Markdown, that's how I discovered and installed this project, which is amazing, btw!
I'm currently trying to understand the structure and how items are organized and regarding the TOC, I've found that it is available under "manifest.yml". However, what if I want to target another file as a TOC? My point is to keep the actual file as a backup and replace it with another file, for instance "my-new-toc.yml". I think it might be easier to target the TOC that will be displayed in the "Subject nav". I haven't found it in the main config file.
What am I missing?
Thanks for your feedback!
I've tried running a local build of the asciidocsy theme via a docker image running ruby v2.6 & bundler v2.2.15, but can't seem to get it to properly render. (see option 1 on capsulecorplab/asciidoctor-docker#3 (comment))
Otherwise, the local Jekyll server seems to work fine
I was going to put this off to just before 1.0, but that was before I realized all the advantages of packaging this project as a Ruby Gem.
I'm not sure all of these steps are required, but they constitute the best practice.
Once those are complete, we can add a gemspec and make a few other changes, and document the whole thing in the Readme. In fact:
The big question here is how to handle the AsciiDocsy docs themselves. Do we add them to the gem or do we just keep them in the project for testing and for building the main site? I need to look at how others handle this.
This epic will be disruptive, so I'm going to do it after 0.1.1, maybe as part of 0.2.0, but definitely by 0.3.0.
Having the theme maintained as a submodule would allow for easier updates to the theme as new releases get published
The _config.yml
file contains lots of references to icon:
property that do not actually render an icon in the output. These are for FontAwesome icons, but they should also work with other systems. They must insert the literal class icon (.icon
) plus the value of this icon
property.
This feature is really just a URL selector. You feed it options, and it browses to the parallel subpath of a new version path.
So if you're at <docs.domain.com>/superproduct/v2.1/getting-started
, the switcher will send you to the same URL but with v2.1
swapped out for another version.
Any number of these can exist on a page, each effectively targeting a different part of the URL.
The only complicated aspect of this is how to build it into the theme's own docs, which are currently unversioned. So this may not get a proper demo until after it is released. Keeping track of your versioned content is far more complicated than providing the front-end switcher for it.
Though I can confirm the nifty asciidocify
filter provided by the jekyll-asciidoc plugin works in a fresh Jekyll repo, something in this codebase is causing an error I've never encountered.
To reporoduce, in _includes/footer.yml
, just change one of the entries that now reads asciidocifyxme
to asciidocify
and run bundle exec jekyll build
.
Liquid Exception: asciidoctor: FAILED: <stdin>: Failed to load AsciiDoc document - no implicit conversion of Symbol into String in <project-path>/_layouts/default.html
This is a Ruby TypeError
thrown inside Asciidoctor as called by the Convert module in jekyll-asciidoc plugin. I cannot figure out for the life of me what could be causing this to behave differently. Even if you just pass it an explicit String (e.g., {{ "some _asciidoc_ string" | asciidocify }}
), it rejects it as a Symbol
type.
The site-nav search field is supposed to search the non-product pages of the site (or maybe those AND the product pages?).
Right now they both search everything. Break these down into 2 indexes and make them search the right stuff.
I removed Lunr.js because it was interfering with Algolia, but I want to put it back in for three reasons.
Publish the next version of asciidocsy theme in a release
Some documentation projects may not need a landing page, in which case it'd be useful to redirect directly to docs/
I cannot believe I'm only just now adding this, but this theme absolutely should have a version with light text on a dark background. This is the style I prefer personally, when done right. Admittedly, I have never done it, as no customer has asked me for it, but I would love to have all my docs in a site like Jekyll's docs or even GitHub's dark theme.
Also wondering if we should stop using "skins" as a way to describe the "look and feel" of the very front-end. It doesn't feel great to use terms like "dark" and "light" with that word in this context.
This should obviously wait until after #24, but I think it is a goal for relatively early (0.3.0?).
The Changes so far section is rather verbose and seems a bit TMI for the average user looking to adopt the asciidocsy theme. This issue is a suggestion to move that section to a CHANGELOG file
Our Navgoco implementation (the left nav menu) uses the classes active
and open
to keep track of what submenus to expand and what active links to highlight. It is supposed to strongly highlight the link to the page the browser is on (this works) and subtly highlight the submenu containing the page the browser is on (this partly works).
While I still intend to reintroduce a YAML-driven landing page (#5), I have come to believe there is still hope for an AsciiDoc-sourced landing-page layout. The current version at https://asciidocsy.netlify.app is a far cry from good, but I only spent 2 or 3 hours on it. How far is it really from something like OpenAPI Generator's landing page, which I quite like? I think all of these elements, plus something clever with admonitions, and I bet it could look pretty good sourced only in AsciiDoc. And I do think that would be easier to spin up when you need to throw together a quick website for a software project, which i want AsciIDocsy to be suited for.
So I would like to return to this landing page in some form, perhaps before I get to #5.
The layout has some bugs. I will collect relatively minor issues in this ticket in case I get a burst of energy. Happy to split off if anyone wants to bite one or more off.
container
because it was not sticky to the bottom outside it. But it needs to span the entire screen -- looks dumb with space around it.Please suggest any layout/CSS issues that you notice in the theme, which is also supposed to be responsive. The docs should look great on mobile devices, of course.
There is a link in each topic page that is intended to drop the sidebars and give you an uncluttered display of the topic article.
It should behave something like the "Print entire section" on a Docsy site.
This is kind of a flagship feature, and I was bummed to not have it done by 0.1.0, but it was getting convoluted. The version I am working from is not jQuery and needs to be converted, which is not my forte. Nevertheless, this one is on me.
tabs show/hide one or more overlayed blocks of content
sourced entirely in standard AsciiDoc, rendered w/ JS
configurable under site.features
degrades gracefully for PDF/no-JS rendering
Right now, most features and other theme settings draw from the site
scope defined by Jekyll configuration files.
It would be nice to provide (at the point of expression in layout/include templates) an alternate source for any object. The object would need the same required properties, but this would enable proviing configuration in data files.
WORKAROUND: For now, the optimal means of achieving this is to source the different site
-scoped objects in separate files and list all files in your Jekyll command using bundle exec jekyll build --config file1.yml,file2.yml
. To break up the giant site.features
scope into multiple files, you''ll need to compile multiple child objects into one, which is not handled by AsciiDocsy alone.
I've started a system for self-documenting the configuration structure to some extent. It's mostly just an experiment, but it needs to be more complete before we can assess usefulness.
Just need to add blank :outfilesuffix:
doc attribute to config.
For the 3.0 release, in which AsciiDocsy will be packaged as a Ruby gem (#31), we will want the AsciiDocsy docs themselves (the documentation that covers the AsciIDocsy theme), to not be based in the root dir of any Jeklyll application using this theme.
For any use of the theme gem, including AsciiDocsy docs's own use, we want the application root to be definitional and for everything in it to override. So we either need to clean up the directory structure and have a distinct Jekyll application inside the gem file structure, or we need to separate the docs out and have a distinct repo use the the way any other application would. This has the advantage of demonstrating a relatively organic use of the theme. Unfortunately, it means another repo, and I think a self-documenting gem is really what's called for, so we'll probably just have a docs/
dir that can be used for Jekyll executions against the content inside it, with a _config.yml
file there that does not interfere with the config for an app that might call the gem.
Before 1.0, this theme needs a thorough audit and correction to conform to a11y standards.
The plan is to have the feedback form use Netlify's simple form capture service, which is free and works without a ton of setup.
That said, whatever cursory setup I tried did not stick.
Additionally, we need a smarter response system than whatever script this is all based on. Let's have options and the echo the user gets based on choice.
When we're delivering this theme as a gem, we don't want a bunch of unaltered vendor code in the package. Create a vendor/
or preferably assets/vendor/
path and a way to get necessary upstream code into that path before build-time. I have admittedly not done this before, but I'm going to require it for the Gemification epic (#31).
Or maybe I'm wrong about this. Feedback or research should yield a confident answer.
It would be handy to have objects in a reference load in the page-nav's TOC, even if they don't have their own headers, which most will not.
The solution here could possibly include adding hidden headers, though that's not perfectly elegant.
What I'm thinking is if you have a DL reference, for instance...
[#setting-a.toc-add]
setting-a:: Here is the definition of setting-a.
[#setting-b.toc-add]
setting-b:: Here is the definition of setting-b.
Use a little jQuery to glean the parent/child/sibling topics and provide links in the topic footer (bottom of the <main>
content container in a topic page).
↑ Previous: Parent Topic Title
(for a first-child topic)← Previous: Sibling Topic Title
Next: Sibling Topic Title →
Next: First Child Topic Title ↓
(for parent topics)Also generate a list of child topics when a topic has kids
in the menu and use that in place of related links (or in addition to?).
Make these configurable, of course.
The conventional way to package a Jekyll theme (and maybe the required way to do it as a Ruby gem?) is as follows:
├── _layouts/
├── _includes/
├── assets/
│ ├── css/
│ ├── images/
│ └── js/
├── _config.yml
├── asciidocsy.gempsec
├── Gemfile
└── README.md
You won't catch me using Markdown for a Readme in this lifetime, but the rest seems worth sticking to. This is basically a deprecation notice on the lack of a base directory assets/
. I did this originally because LiquiDoc Ops had a concept of assets as well, and I did not want them to get confused. (Additionally, on some level it bothers me to call image, JS, and CSS files "assets" but exclude template files -- this could just be me.) I believe the concept of content assets is coming out of LDOps anyway, so it just makes good sense to standardize around this method and call the site files "assets".
I don't think it makes sense to have Gemfile.lock
in .gitignore
, since the point of the lock file is to provide a reproducible build of dependencies needed to run a working site. I spent a couple of hours trying to debug why bundler
was producing inconsistent builds when experimenting between jekyll 3.8 & 4.2, committing relevant changes as I go (as one should), until I noticed git
wasn't tracking changes to Gemfile.lock
after running bundle lock
.
asciidocsy-jekyll-theme/.gitignore
Line 2 in 623eeab
I already dislike how what I'm calling "togglers" is work in this theme, and I'm sick of mixing up "toggles" and "togglers".
Also, as a pedant, it bothers me that this utility does not so much toggle content as it switches content.
So let's call them switchers, but let's also make it possible to have them be simple on/off toggle capability using a checkbox rather than radio button concept.
In several places, we will use JS/JSON on the very front end to display significant blocks of text drawn from YAML. It would be great if we could asciidocify this first, where applicable.
This probably means re-doing the jsonify
Jekyll/Liquid filter, one way or another. Maybe an asciidoc-jsonify
filter? Or, we could just use an include and iterate through the object and asciidocify as we go. That wouldn't be too hard or resource intensive.
Hugo has a Git info variable that fetches the last commit associated with a contents page. Is it possible to do the same in Asciidocsy?
I have not really thought this one through, but it came up as I was documenting the nav menus, so I wanted to pin it on the board.
I believe all of the manually configurable menus (site nav in the header, subject nav in the left sidebar, and company nav in the footer) could accommodate additional nesting.
I have run a quick test on Navgoco (subject nav), and it can handle at least another tier of nesting. I am just not sure I want to support that.
The Bootstrap-driven site nav can definitely handle more nesting. See https://bootstrap-menu.com/detail-multilevel.html. This can look rather nice, but is it ever necessary? I haven't been asked to implement anything that hardcore for a site menu, but it wouldn't be hard.
But I might have to put my foot down before trying this in the footer. There is plenty of room down there, though stream-of-consciousness I guess I can fathom wanting to have lots of links in the footer but keeping it sparse at first glance from a design perspective.
Anyway, the issue is placing an extension hook at the deepest point of nesting, in case you want to continue the iteration in your own templates.
The original idea for toggle handlers included facet-style toggles for classes independent of others. So, a direct show/hide toggle for one class at a time, checkbox style.
I don't think there's any complex logic in here -- if multiple competing classes are assigned to an element/block, we might want the ability to select an all or one paradigm, whereby a class will show only when all classes are toggled on or when at least one is. We probably want to incorporate that as much as we can to leave the options wide open.
This did not make it into #48, but it should get in by 1.0.
I'm not terribly upset with the state of the theme's CSS, as such things go for a rapidly changing theme. But before it gets out of hand, I want to organize it a way I find more ideal.
I had started trying to use the original Hugo Docsy's SCSS (Sass) files, which was sort of working, but there were some quirks I did not have the patience to deal with (or even document). This would not be a terrible place to start.
Docsy also maintains a vendor/
path for Bootstrap and FontAwesome, which I like. We can do this in #32. Once we're in Sassville, we don't have to impose preferred colors in the CSS, and we can get Bootstrap out of the repo. Let's add Asciidoctor Stylesheet Factory to the vendor/
bin as well.
NOTE: This ticket is partly resolved so has been edited to reflect new objective.
Apparently I never finished the code to display like-tagged topics as "Related Topics", which currently sits at the bottom of each topic as a lone header: "See these other topics".
I stopped because I was trying to figure out the best way to implement this feature. Do we enable a page variable that lists tags, and then cross-reference every so-tagged topic? This is pretty standard.
Do we enable specific entries for links that would not match the tags?
I'd love some feedback on this.
I've never had a client ask me for a landing page as part of a documentation theme. Nevertheless, there are a few reasons I want AsciiDocsy to include a robust landing-page capacity.
The landing page theme I've already made for one case (but not yet generalized or open-sourced) is not done mainly with AsciiDoc. In fact, the only AsciiDoc at all is inside strings of text, which are nearly all stored in YAML objects that define the sections.
Here is some sample markdown driving that site.
The first thing that I did was create templates (or convert, from Agency and Airspace themes) for the different segments. These templates required lots of arguments when included, so I created elaborate includes like the following:
{% include features.html
id = "ops"
title = "The Unity Platform"
desc = "Bringing technical writers and engineers together."
nodes = site.data.features.primary %}
{% include gridfolio.html
id = "showoff"
title = "For Documentation Worthy of Your Product"
desc = "LiquiDoc Ops is JAMstack-based, offering complete front-end freedom.<br/>It also ships with a killer versioning-ready docs theme."
nodes = site.data.folio.output.portal %}
{% include quote.html
id = "alicia-quote"
text = "After searching and testing options for almost a year, I helped design and pilot LiquiDoc Ops. Not only has the LiquiDoc Ops toolchain proven to be a refreshingly nimble and sophisticated way for me to manage our content, but my developer colleagues love working with it."
attribution= "Alicia Duncan, Lead Technical Writer, <a href='https://www.digi.com/resources/documentation/digidocs/embedded/index.html' target='_new'>Digi International</a>" %}
{% include features.html
id = "features-secondary"
title = "Enterprise- and Suite-ready"
desc = "LiquiDoc Ops is designed for documenting complex products with awkward version-divergence problems by accommodating their necessarily complex sourcing schemes."
nodes = site.data.features.secondary %}
Each of these blocks of code of course calls a file that embeds the content inside HTML directly. That works pretty well, mind you, but honestly Liquid is the LAST of all the markups I use that I actually want to write content in. Liquid is really not for content -- especially not its {% include %}
tagging process. Ew.
That's why I came up with a YAML-driven solution. Here i an example of the source of content that populated some of these includes.
primary:
- name: Free and Open
text: All components are free/freemium and open standards/FOSS
icon: folder-open-o
role: proprietary
- name: Source Controlled
text: No binary database, nothing proprietary, everything in Git
icon: git
role: proprietary
- name: Version Aware
text: Docs and tools that know all your products' permutations
icon: sort-numeric-desc
role: markdown
- name: Enterprise Scale
text: LiquiDoc Ops means first-class docs across the organization
icon: industry
role: markdown
- name: XML Free!
text: Lightweight markup means all the power with none of the bloat
icon: code slash
role: proprietary
- name: Writer-friendly Tools
text: Clide is the unifying CLI utility for command-line phobes
icon: pencil
role: markdown
secondary:
- name: Full Spectrum
text: Developer docs (including internal) and user-facing docs
icon: address-card
role: proprietary,markdown
- name: Output Anything
text: Helpsites, manuals (HTML + PDF), JSON, even JS-driven presentations
icon: file-image-o
role: proprietary,markdown
- name: Output Continuously
text: CI with instant delivery and deployment, for staging and production
icon: rocket
role: proprietary
- name: Frameworked
text: Libraries, conventions, and utilities for rapid development
icon: briefcase
role: markdown,proprietary
- name: Strategic Divergence
text: Built-in options for handling edition/version differences
icon: code-fork
role: markdown
- name: RBAC
text: Roles-based access control, for workspace/UI sanity
icon: user-times
role: markdown
I have not seen anyone else do this, so it might be a terrible idea, but I found it really rewarding.
Now, much as I prefer authoring in YAML over Liquid, my favorite format for authoring is of course AsciiDoc. The problem is, however, that just as Markdown does not make great sense for technical authoring, AsciiDoc does not make a great source for landing pages.
The truth is almost certainly that no single content markup format is or could ever be ideal for a landing page. But even the semantics of AsciiDoc are all off, so we'd almost be better off creating a dreaded domain-specific language (DSL) for landing pages. Well, for me, that just means using YAML with some semantic intent, which is what I've done here.
The landing page currently in use here is actually my second attempt to create a landing-page layout/theme that could be driven by AsciIDoc only, with optional PDF output (because why not?), perhaps with very small snippets of passthrough (verbatim) HTML code, for stuff that wouldn't work good in PDF anyway and could thus be conditioned out. I am ready to call this second earnest attempt a failure. I have considered creating a different set of AsciiDoc conversion templates, but that feels like pouring lots more work into an idea that just isn't good enough to warrant the effort.
So I think I'm going to introduce my novel Landing page method and the basic theme that makes it work, right here inside AsciiDocsy. It should work independently of the rest of the theme, in fact, so you could use it for just a landing page, as I have.
Clicking the "Print-friendly" button causes the navbar to disappear for about a half second, but then reappears.
This was working at some point, but now it is not. Other languages work (see https://asciidocsy.netlify.app/docs/theme/syntax-highlighting). Asciidoctor is doing its job and creating the right class...
Algolia requires their logo for free-tier use of their services, which we are using. We definitely need to get that into the template.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.