The canonical gem source for LiquiDoc, a ruby-based documentation parsing and rendering utility enabling advanced builds with Asciidoctor, Jekyll, Liquid, and semi-structured data files.
Jekyll is pretty well primed to run against many of the same files already in use by LiquiDoc and Asciidoctor. With the Jekyll plugin called jekyll-asciidoc, we can parse AsciiDoc "pages" and "posts" just like Jekyll parses Markdown. I think the key will be to feed a config file location to LiquiDoc, and that config file can do pretty much everything else, as with a direct call to bundle exec jekyll serve. We'll also want deploy options using Travis CI and GitHub pages, at least, by default. The more plug-and-play, the better.
This would call Jekyll operations natively and log to screen normally.
I've included the attribute base: just as a placeholder: I don't know if the config file can be stored outside the root from which Jekyll will crawl all non-excluded directories looking for valid files to parse into HTML or otherwise handle. This will take some research, but ideally we can store multiple custom-named config files for multiple Jekyll operations. I don't have a solid use case for this, but I can imagine some based on experience, such as needing different sites for internal docs and customer-facing docs, built from the same repo but needing totally different site deployments.
Any Jekyll operation will be a "deploy" action, since the jekyll serve operation is a final phase, even if it doesn't push to the web. A local docs site deployment is still a deployment.
I have not suggested the platform: attribute elsewhere, but its my way of demonstrating I would love to see LiquiDoc extended to other site-deployment or build/testing utilities. So platform: is where we can express what third-party utility we'll be engaging for a deployment. I don't want to make this optional now, even if it only works with Jekyll, because I really do see this changing.
Jekyll is pretty well primed to run against many of the same files already in use by LiquiDoc and Asciidoctor. With the Jekyll plugin called jekyll-asciidoc, we can parse AsciiDoc "pages" and "posts" just like Jekyll parses Markdown. I think the key will be to feed a config file location to LiquiDoc, and that config file can do pretty much everything else, as with a direct call to
bundle exec jekyll serve. We'll also want deploy options using Travis CI and GitHub pages, at least, by default. The more plug-and-play, the better.This would call Jekyll operations natively and log to screen normally.
I've included the attribute
base:just as a placeholder: I don't know if the config file can be stored outside the root from which Jekyll will crawl all non-excluded directories looking for valid files to parse into HTML or otherwise handle. This will take some research, but ideally we can store multiple custom-named config files for multiple Jekyll operations. I don't have a solid use case for this, but I can imagine some based on experience, such as needing different sites for internal docs and customer-facing docs, built from the same repo but needing totally different site deployments.Any Jekyll operation will be a "deploy" action, since the
jekyll serveoperation is a final phase, even if it doesn't push to the web. A local docs site deployment is still a deployment.I have not suggested the
platform:attribute elsewhere, but its my way of demonstrating I would love to see LiquiDoc extended to other site-deployment or build/testing utilities. Soplatform:is where we can express what third-party utility we'll be engaging for a deployment. I don't want to make this optional now, even if it only works with Jekyll, because I really do see this changing.