“Bootstrap” this Theme

Assuming you don’t just want to build a site that promotes and documents the AsciiDocsy theme itself (I got this), your goal must be to apply AsciiDocsy to your own documentation set.

Cool. The first step is to review the entries in _config.yml and translate them to your own application.

The site at localhost:4000 will regenerate incrementally whenever you change pretty much any file in the repo. A key exception is _config.yml. To get site settings and site-scoped variables to reflect in a build, use kbd:[Ctrl+C] to stop the server, then re-run bundle exec jekyll s.

AsciiDocsy is designed to be modified mostly through YAML configuration and datafile settings. See Configuring AsciiDocsy in the theme docs for more.

LiquiDoc Ops Integration (More Coming Soon)

This theme is meant to go be embedded in the theme/ path of a LiquiDoc Ops application (probably as theme/asciidocsy/). Repoint any Jekyll configuration settings from theme/[<theme-name>/] to this new path.

Deploying an AsciiDocsy Jekyll Site

The build operation generates static HTML files and other artifacts that can be deployed to any static-site server. Most docs-as-code toolchains incorporate “continuous integration” and “continuous deployment” (CI/CD), integrating the docs build into review workflows and the timely release of the production (“live”) site.

Automation with Netlify

My preferred out-of-box deployment with full production hosting as well as staging capabilities is definitely Netlify. You can sign in with your GitHub/GitLab authorization and have site up in under a minute.

  1. Create a Netlify account.

  2. Add a site.

  3. Select your repo.

  4. The build command (bundle exec jekyll build) and target path (_site/) should already be filled out.

You can trigger builds through the Netlify UI or by simply merging a commit to the main (or other default) branch.

If you set up CI/CD on another such platform, please contribute the instructions here. I have no affiliation with or allegiance to Netlify or GitHub.

DIY DocOps

If you or your DevOps/IT department have ideas for static-site hosting and integration into an existing CI/CD platform, this task should be fairly straightforward.

Build Operation

You defintely want to:

  1. Require Ruby 2.4+.

  2. Run bundle install.

  3. Run bundle exec jekyll build.

  4. Copy files from the destination dir (_site/ by default) to your staging or production server.

Continuous Integration

You will probably also want to:

  • Establish build triggers for:

    • merge/pull requests (staging deploy)

    • merges to the main branch (production deploy)

  • Establish tests, perhaps starting with:

Deployment

The site is configured to be served at a domain or subdomain root, such as www.yourdocumentationwebsite.com or docs.yourcompan.io. If you serve them at a path beneath such a URL, like www.yourcompany.com/docs, add that path to your destination: setting in _config.yml and copy from that path to your webserver.

Feedback, please.