In my last post I briefly mentioned how you could make a local website out of your docs using only

I have a lot of documentation that I update and refer to everyday. It is marked up with AsciiDoc. I find the best way to work with it is to organize all my docs and link them together into a mini-website on my laptop.

Templates to get you started

To get you started, I’ve created a few docs and linked them together so you can quickly see how this works.

Start by cloning this repo: Asciidoctor-LivePreview-Website

You can just download the .ZIP and place the files together in a directory.

Asciidoctor.js Live Preview

Install the Asciidoctor.js Live Preview in your browser if you don’t already have it

Set the options for it

  • Safe mode: unsafe

  • Preview .txt files: (so you can use these .txt files in addition to .adoc files)

  • Click save.

If you are using Firefox change all your file extensions to .adoc because there’s no option to use .txt at this time.

Open the index.txt in your browser

Find the directory where you copied the text files from the Asciidoctor-LivePreview-Website repo.

Right-click on index.txt and open with Chrome.

You should see it open and render like a mini-website. Click around and test it out.

Start Editing it.

When you take look at the text files you’ll notice that the index.txt file has

 include::header.txt[]

 include::footer.txt[]

You can use those in all your docs to create a navigation menu at the top and a mini-sitemap at the bottom. You’ll find header.txt and footer.txt in the repository. I’ve used AsciiDoc tables to make the columns.

Or leave them off and just add a link back to the index.txt page

I usually edit in one window on the left and preview the changes in Chrome on the right.

Linking your docs together

The main AsciiDoc code you’ll need to hook your docs together is link. It’s pretty straight forward to use. It looks like this:

link:AnotherDocument.txt[Another Document]

Bookmark your index.txt file

Don’t forget to bookmark your main doc. If index.txt seems too 'WebDev' like, you might want to name it README.txt. Then write links to all your other docs creating a simple website.

Not quite a wiki

It is not the same as a wiki but it is so simple to edit you might think it’s better than a wiki. Store your files in a repository and you’ll even have the history of changes you make.

You could build an intranet site on your network using this concept.

Spread the word