/ADOC2Blog

ASCIIDoctor to Blog generator

Primary LanguageHTML

ASCIIDoctor to Blog Utility

Table of Contents

Over the years I have tinkered with the idea of using ASCIIDoctor documents as the basis for a blog service. The Blog would be statically delivered and as damn simple as possible.

A PDF version of this document is available at this Link

1. Introduction

I use ASCIIDoctor to do the majority of my documentation and have gotten good at it with special editor extension and snippets.

I have looked at a number of Open source solutions and most of them are either too complex or difficult to implement.

  • Hugo - Based on Go and a defined file structure that doesn’t allow the article to exist in a directory atomically.

  • Gatsby - Difficult to install and is geared more towards document repository

  • Antora.org - Requires GIT repositories to create a document site generator, too many unneeded features

  • Vue based - Flexible but used GraphQL for access to even the filesystem, ASCIIDoc not mentioned

2. Requirements

These are the requirements for a basic utility to manage ASCIIDoctor files specifically and generate a blog automatically

  • Use Blog articles as separate directories

  • Use ASCIIDoctor as the primary files for articles

  • Use the content of the ASCIIDoctor file to drive the indexing

    • The (=) title becomes the tile of the article

    • The preamble (The first paragraph of the document)

    • Date from the date line of the header

  • index.html generated from index.adoc to all for template of index to be changed

  • Blog order article is determined by a single text file in roo order.txt with a list of the directory name in the order they should appear in the blog

    • Delete an article by (*) it in the 'order.txt

  • Use a FTPSync command to help move (New/Updated) generated content into web server

  • Auto generate HTML & PDF if the coersponding ADOC is more than 1 day old

  • Auto generate (Optional) the order.txt file of the sub-folder of the blog

3. Prerequisites

  • Definition of Blog article file naming

    • readme.adoc for main document

    • readme.png (Optional) for Blog article image

    • ALl sub-directories in Blog article directory will be transferred except for .exclude folder

  • Node FTPSync - To manage transfer of generated updates

4. Folder / File Structure

Here is a diagram of the required file structure for ADOC2Blog to work.

Each Blog Article folder is Atomic which means all of the assets for that article are in the folder.

Folder / File Structure
Figure 1. Folder / File Structure

5. order.txt file

This is a simple text file with the names of the Blog Article folders to be included in the generated Blog Article web site.

Folders not listed here will NOT be in the generated web site.

Folders staring with an * will be hidden and will NOT be in the generated web site. In this example New dog grooming methods will not be in the generated web site

Example `order.txt` file
Figure 2. Example order.txt file

6. Business Rules

  1. 'order.txt' file must exist, fatal if it doesn’t

  2. Directory listed in order.txt is missing

  3. Missing readme.adoc file in the directory being processed - Warning directory skipped

  4. Missing title line (= title) warning, use directory name

  5. Missing date (v2.1,07/21/2019:type) warning, use todays date

7. Web site

The web site will be generated based on the layout in the index.adoc template. This template can be modified for the page scaffolding. Additional content or directions could be added.

Blog Article Web Page Example
Figure 3. Blog Article Web Page Example

8. Developer notes

  • Standard NPM Init

  • Other NPM Libraries

    • Chalk - Color display in terminal window

    • Figlet - Large ASCII characters

    • Clear - Clear the terminal screen

9. Document History

Table 1. Document History
Date Version Author Description

07/22/2019

V2.1c

JHRS

Business rules, thanks Deb!!

07/19/2019

V2.1b

JHRS

Initial version