AsciiDocsy Theme Documentation (Site)

This repository contains the technical documentation for the AsciiDocsy Jekyll Theme.

The rendered documentation uses the AsciiDocsy theme, of course.

Build the Docs

With a Ruby environment in place, these steps will perform a local build of the AsciiDocsy Documentation site.

1. Clone (or download and inflate) this repo.

   Clone

   git clone [email protected]:DocOps/asciidocsy-docs-www.git

   Download & inflate

   

   💡	Use git clone [email protected]:DocOps/asciidocsy-docs-www.git my-asciidocsy-project to name the containing directory something other than asciidocsy-docs-www. Or clone normally and freely rename the directory at any time.

2. Change to the new directory.

   Example

   cd my-asciidocsy-project

3. Install Ruby dependencies.

   bundle install

   If Bundler is not installed, gem install bundler, then repeat bundle install.

4. Generate and serve the demo site.

   bundle exec rake serve

You should now be able to view the site at http://localhost:4000 in any local browser.

You will find the generated files at _site/.

⚠️	If you wish to generate and serve a version of AsciiDocsy’s docs, please DO NOT change the site.canonical-url value, as it will harm the search-engine optimization of this site (and yours). Please DO make a note in the README and elsewhere linking prominently to the canonical version.

Exemplary AsciiDocsy

You are welcome to use this implementation of AsciiDocsy as a starting point for your own docs covering your own product.

Learn more about applying AsciiDocsy to your use case in the Bootstrapping guide.

This documentation repository constitutes a somewhat unconventional Jekyll application. Much of the content and data source is derived from a Git submodule reference, treating the AsciiDocsy gem repository itself as a source. This enables me to document AsciiDocsy in its own repo. It also leaves generating and deploying the docs to a separate repository that is itself a Jekyll/AsciiDocsy application.

This dependency and build process is coordinated by the Rakefile in the root of this repo. A few rake commands initiate the cascade of commands required to assemble the AsciiDocsy docs source, mixing content from the gem repo in with Git-ignored local paths (content/topics/asciidocsy/, _data/subjects/asciidocsy/)

I recommend using AsciiDocsy in a similar fashion with your own product source.