In my last post I briefly mentioned how you could make a local website out of your docs using only
A text editor, like Notepad
A browser extension in Chrome Asciidoctor.js Live Preview
And some AsciiDoc links
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)
|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
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:
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.