Design Docs - Site Converter Rough Design

Overview

This page roughly describes the system which generates and serves Jekyll (GitHub Pages) site backed by Confluence Cloud instance.

The author can edit the content in the Confluence Cloud, GitHub Actions fetches and converts them into data for Jekyll, GitHub Pages serves the content with configured custom domain.

Involved Components

• Atlassian Confluence Cloud instance

• GitHub Repository

  • https://github.com/haruki-sugarsun/text.sickhack.net and gh-pages branch.

  • Actions to automatically fetch and convert content https://github.com/haruki-sugarsun/text.sickhack.net/actions

• GitHub Pages

  • with a custom domain

Diagram

                         +--------------------------------------------------------+
                         | text.sickhack.net repository                           |
                         |                                                        |
                         |                                                        |
+------------------+     |  +-------------------------+    +-------------------+  |
|Confluence        |     |  | GitHub Actions          |    | gh-pages branch   |  |
|                  |     |  |                         |    |                   +--+->text.sickhack.net
|  -page content   +-----|->|  -Recursive fetch       +--->|  -Jekyll          |  |
|  -editor         |fetch|  |  -Metadata processing   |push|                   |  |
|  -attachments    | by  |  |  -HTML Conversion       |    +-------------------+  |
|                  | REST|  |  -Rule-based extra      |                           |
+------------------+     |  |                         |                           |
                         |  +-------------------------+                           |
                         |                                                        |
                         +--------------------------------------------------------+

(powered by https://asciiflow.com/)

Components

See other documents for the details for each component.

GitHub Actions

Converter

Converter code is currently managed in my private repository not published to GitHub.

In short, it fetches the pages by page id (e.g. 12345) and generates files (e.g. _pages/12345.html) for Jekyll with adding some Front Matter (http://jekyllrb-ja.github.io/docs/front-matter/ ) to help page generation.

GitHub Pages

• published from gh-pages branch, with Jekyll-based GitHub-pages

• with custom domain text.sickhack.net.

Converter Internals

“concept” Definitions

• A “tree”:

  • Pages under the specified “root” page in the source Confluence.

• A “page”

  • a single page in the source Confluence

• A “content”

  • API response fetched with Confluence API.

  • especially “raw content” is the returned JSON returned

“verb” Definitions

• Process (a tree/a page)

  • Fetch (a tree/a page)

  • Analyze (a tree/a page)

  • Convert (a tree/a page)

Cache Directory Structure

• The cache directory is specified by the command-line option --cache-dir

TODO: write.

Output Directory Structure

TODO: write.

Flags and Phases Relationships

TODO: write.

Phase \ Flag	root-page-id process-one-target-id	use_cache (and cache mode later)
fetch
analyze
convert