ciigo

README

Welcome to ciigo

ciigo is a program (as in command line interface, CLI) and a library (as in Go package) to write static web server with embedded files using AsciiDoc and Markdown markup format.

As showcase, the following websites are build using ciigo,

• kilabit.info - Source code.

• golang-id.org - Source code.

Features,

• Simple. There is only three main commands: convert, embed, and serve.

• No themes, built your own template and style. Except for default HTML template and embedded CSS, there is no other selection of theme that you can "pre-installed".

• No layout, you are free to structure your sites, using normal directory and file layout. Directory that contains "index.adoc" or "index.md" will be served as is. For example "/my/journal/index.adoc" can be accessed as "/my/journal/" or "/my/journal/index.html".

ciigo as CLI

ciigo as CLI can convert, generate, and/or serve a directory that contains markup files, as HTML files.

Installation

The installation require the git and Go tools which you can download it here.

First, clone this repository somewhere, let say under your $HOME/src directory,

$ mkdir -p $HOME/src/
$ cd $HOME/src
$ git clone https://git.sr.ht/~shulhan/ciigo

Run "go install" on ./cmd/ciigo,

$ cd $HOME/src/ciigo
$ go install ./cmd/ciigo

This will install the ciigo into your $GOBIN. If you did not know where $GOBIN is, run "go env" and check for GOBIN environment variable. It usually in $HOME/go/bin.

Usage

ciigo [-template <file>] [-exclude <regex>] convert <dir>

Scan the "dir" recursively to find markup files (.adoc or .md) and convert them into HTML files. The "-template" file is optional, default to embedded HTML template.

ciigo [-template <file>] [-exclude <regex>] [-out <file>] \
	[-package-name <string>] [-var-name <string>] \
	embed <dir>

Convert all markup files inside directory "dir" recursively and then embed them into ".go" source file. The output file is optional, default to "ciigo_static.go" in current directory. The package name default to main. The variable name default to memFS.

ciigo help

Print the usage.

ciigo [-template <file>]  [-exclude <regex>] [-address <ip:port>] \
    serve <dir>

Serve all files inside directory "dir" using HTTP server, watch changes on markup files and convert them to HTML files automatically. If the address is not set, its default to ":8080".

ciigo version

Print the current ciigo version.

Example

In this repository, we have an "_doc/example/" directory that we can try using ciigo.

$ tree _doc/example
_doc/example/
├── custom.css
├── favicon.ico
├── html.tmpl
├── index.adoc
├── index.css
└── sub
    └── index.adoc

First, lets convert all AsciiDoc files (.adoc) inside the "_doc/example" directory recursively,

$ ciigo convert ./_doc/example
2025/01/06 19:17:07 convertFileMarkups: converting _doc/example/sub/index.adoc
2025/01/06 19:17:07 convertFileMarkups: converting _doc/example/index.adoc
$

Then serve it under HTTP server,

$ ciigo serve ./_doc/example/
2025/01/06 19:17:47 ciigo: starting HTTP server at http://127.0.0.1:6320 for "./_doc/example"

While the program still running, open the http://127.0.0.1:6320 in your browser. Notice that we have "sub" directory. Lets open http://127.0.0.1:6320/sub/ in your browser too. As we can see, the style of "/sub/" page is different because they use custom style defined using

:stylesheet: custom.css

inside the "/sub/index.adoc" file. This is one of powerful feature of ciigo, where different page can have their own style.

Lets convert again but now using new "-template",

$ ciigo -template _doc/example/html.tmpl
$

Nothing happened, why? Because none of the markup files is newer than our previous generated HTML. To force converting all markup files, we can update the modification time of our template file,

$ touch _doc/example/html.tmpl
$

or delete all the HTML files,

$ find _doc/example/ -name "*.html" -delete
$

and then run the convert command again.

$ ciigo -template ./_doc/example/html.tmpl convert ./_doc/example/
2025/01/06 19:28:17 convertFileMarkups: converting _doc/example/sub/index.adoc
2025/01/06 19:28:17 convertFileMarkups: converting _doc/example/index.adoc
$

Run the serve command again to preview our new generated HTML files,

$ ciigo serve ./_doc/example/
2025/01/06 19:36:07 ciigo: starting HTTP server at http://127.0.0.1:6320 for "./_doc/example"

You can see now that the new template rendered, with "ciigo" in the top-left as tile and a "Sub" menu at the top-right.

Writing content and viewing it live

The "ciigo serve" command able to watch for new changes on markup files and convert it automatically to HTML without need to run "convert" manually.

Lets run the serve command again on "_doc/example" directory,

$ ciigo serve ./_doc/example/
2025/01/06 19:46:54 ciigo: starting HTTP server at http://127.0.0.1:6320 for "./_doc/example"

Create new directory "journal" under "_doc/example",

$ mkdir -p ./_doc/example/journal/
$

Inside the "journal" directory, create new file "index.adoc" with the following content,

= My Journal

Hello world!

Go back to the browser and open http://127.0.0.1:6320/journal/ and we should see new HTML page generated with the above content.

Each time we refresh the browser, ciigo will check if the markup file is updated and then convert it automatically to HTML and return it to browser.

Lets try updating the "journal/index.adoc" into

= My Journal

Hello ciigo!

and create or update the ".ciigo_rescan",

$ touch _doc/example/.ciigo_rescan
$

and when we refresh the browser, we should see the page being updated.

Deployment

Once we have write the content as we like, we can deploy the generated HTML files and other assets files to the server.

For example, using rsync(1) we can deploy the "_doc/example/" excluding the hidden files (start with ".") and files with extension ".adoc", ".md", and ".tmpl"; by issuing the following command,

$ rsync --exclude='.*' \
    --exclude='*.adoc' --exclude='*.md' --exclude='*.tmpl' \
    --recursive --archive \
    _doc/example/ \
    user@myserver:/srv/pub/

ciigo as library

Using ciigo as library means you do not need to install the ciigo program itself, but you write a Go code by importing the ciigo module into your own program.

This model gives flexibility. You can adding custom functions, custom HTTP endpoints, and many more.

For an example on how to use ciigo as library see the code at internal/cmd/ciigo-example.

That's it, happy writing!

Custom Stylesheet

When converting an asciidoc or markdown to HTML, ciigo by default embed their own stylesheet. This is to provide better user experiences when using the program for the first time.

To turn it off in asciidoc document, set the stylesheet attribute with "!" suffix,

= Title
:stylesheet!:

To turn it off in markdown document, set the value to false,

---
stylesheet: false
---
# Title

To combine default stylesheet with custom CSS, set the value to "default" and the file name of custom CSS, separated by comma. This is the recommended way to use custom stylesheet since it can be set only on specific pages.

// In asciidoctor:
:stylesheet: default, custom.css

// In markdown:
stylesheet: default, custom.css

To disable default stylesheet and only using custom CSS, set the value only to the file name of custom CSS.

Another way to use custom stylesheet is by creating your own template and pass it to serve or convert command. This method makes the stylesheet applied to all pages.

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
{{- range $k, $v := .Metadata}}
    <meta name="{{ $k }}" content="{{ $v }}" />
{{- end }}
    <title>{{.Title}}</title>
    <link rel="stylesheet" href="/custom.css" />
  </head>
...

Links

https://git.sr.ht/~shulhan/ciigo - Link to the source code.

https://lists.sr.ht/~shulhan/ciigo - Link to development and discussion.

https://todo.sr.ht/~shulhan/ciigo - Link to submit an issue, feedback, or request for new feature.

https://pkg.go.dev/git.sr.ht/~shulhan/ciigo - Go module documentation.

Change log - Log of each releases.

License

Copyright 2022 Shulhan <ms@kilabit.info>.

This software is licensed under GNU General Public License version 3.0 or later.

Documentation

Overview

Package ciigo is a program to write static web server with embedded files using the asciidoc markup languages.

For more information see the README file at the page repository https://sr.ht/~shulhan/ciigo.

Index

• Constants
• Variables
• func Convert(opts ConvertOptions) (err error)
• func GoEmbed(opts EmbedOptions) (err error)
• func Serve(opts ServeOptions, convertOpts ConvertOptions) (err error)
• func Watch(opts ConvertOptions) (err error)
• type Ciigo
  • func (ciigo *Ciigo) Convert(opts ConvertOptions) (err error)
  • func (ciigo *Ciigo) GoEmbed(embedOpts EmbedOptions) (err error)
  • func (ciigo *Ciigo) InitHTTPServer(serveOpts ServeOptions, convertOpts ConvertOptions) (err error)
  • func (ciigo *Ciigo) Serve() (err error)
  • func (ciigo *Ciigo) Watch(convertOpts ConvertOptions) (err error)
• type ConvertOptions
• type Converter
  • func NewConverter(htmlTemplate string) (converter *Converter, err error)
  • func (converter *Converter) SetHTMLTemplateFile(pathHTMLTemplate string) (err error)
  • func (converter *Converter) ToHTMLFile(fmarkup *FileMarkup) (err error)
• type EmbedOptions
• type FileMarkup
  • func NewFileMarkup(filePath string, fi os.FileInfo) (fmarkup *FileMarkup, err error)
• type ServeOptions

Constants

const (
	// DefaultRoot define default Root value for ConvertOptions.
	DefaultRoot = `.`
)

Variables

var Version = `0.17.0`

Version define the latest tagged release of this module.

Functions

func Convert

func Convert(opts ConvertOptions) (err error)

Convert all markup files inside directory "dir" recursively into HTML files using ConvertOptions HTMLTemplate file as base template. If HTMLTemplate is empty it will default to use embedded HTML template. See template_index_html.go for template format.

func GoEmbed

func GoEmbed(opts EmbedOptions) (err error)

GoEmbed generate a static Go file that embed all files inside Root except the one that being excluded explicitly by ConvertOptions Exclude.

It convert all markup files inside directory "dir" into HTML files, recursively, and then embed them into Go file defined by EmbedOptions.GoFileName.

If HTMLTemplate option is empty it default to use embedded HTML template. See template_index_html.go for template format.

func Serve

func Serve(opts ServeOptions, convertOpts ConvertOptions) (err error)

Serve the content under directory "ConvertOptions.Root" using HTTP server at specific "ServeOptions.Address".

func Watch

func Watch(opts ConvertOptions) (err error)

Watch any changes on markup files on directory Root recursively and changes on the HTML template file. If there is new or modified markup files it will convert them into HTML files using HTML template automatically.

If the HTML template file modified, it will re-convert all markup files. If the HTML template file deleted, it will replace them with internal, default HTML template.

Types

type Ciigo

type Ciigo struct {
	HTTPServer *libhttp.Server
	// contains filtered or unexported fields
}

Ciigo provides customizable and reusable instance of ciigo for embedding, converting, and/or serving HTTP server. This type is introduced so one can add HTTP handler or endpoint along with serving the files.

func (*Ciigo) Convert

func (ciigo *Ciigo) Convert(opts ConvertOptions) (err error)

Convert all markup files inside directory ConvertOptions.Root recursively into HTML files using ConvertOptions.HTMLTemplate file as base template. If HTMLTemplate is empty it use the default embedded HTML template. See template_index_html.go for template format.

func (*Ciigo) GoEmbed

func (ciigo *Ciigo) GoEmbed(embedOpts EmbedOptions) (err error)

GoEmbed embed the file system (directories and files) inside the ConvertOptions.Root into a Go code. One can exclude files by writing regular expression in ConvertOptions.Exclude.

func (*Ciigo) InitHTTPServer

func (ciigo *Ciigo) InitHTTPServer(serveOpts ServeOptions, convertOpts ConvertOptions) (err error)

InitHTTPServer create an HTTP server to serve HTML files in directory defined in "ConvertOptions.Root".

This method initialize the Ciigo.HTTPServer so one can register additional endpoints before running the HTTP server.

func (*Ciigo) Serve

func (ciigo *Ciigo) Serve() (err error)

Serve start the HTTP web server.

func (*Ciigo) Watch

func (ciigo *Ciigo) Watch(convertOpts ConvertOptions) (err error)

Watch start a watcher on ConvertOptions.Root directory that monitor any changes to markup files and convert them to HTML files.

type ConvertOptions

type ConvertOptions struct {
	// Root directory where its content will be embedded into Go source
	// code.
	// Default to DefaultRoot if its empty.
	Root string

	// Exclude define regular expresion to exclude certain paths from
	// being scanned.
	Exclude []string

	// HTMLTemplate the HTML template to be used when converting markup
	// file into HTML.
	// If empty it will default to use embedded HTML template.
	// See template_index_html.go for template format.
	HTMLTemplate string
	// contains filtered or unexported fields
}

ConvertOptions define the options to use on Convert function.

type Converter

type Converter struct {
	// contains filtered or unexported fields
}

Converter a single, reusable AsciiDoc converter.

func NewConverter

func NewConverter(htmlTemplate string) (converter *Converter, err error)

NewConverter create and initialize Converter with HTML template. If htmlTemplate is empty, it will use the internal, predefined template.

func (*Converter) SetHTMLTemplateFile

func (converter *Converter) SetHTMLTemplateFile(pathHTMLTemplate string) (err error)

SetHTMLTemplateFile set the HTML template from file.

func (*Converter) ToHTMLFile

func (converter *Converter) ToHTMLFile(fmarkup *FileMarkup) (err error)

ToHTMLFile convert the AsciiDoc file to HTML.

type EmbedOptions

type EmbedOptions struct {
	ConvertOptions
	memfs.EmbedOptions
}

EmbedOptions define the options for calling GoEmbed function.

type FileMarkup

type FileMarkup struct {
	// contains filtered or unexported fields
}

FileMarkup contains the markup path and its kind.

func NewFileMarkup

func NewFileMarkup(filePath string, fi os.FileInfo) (fmarkup *FileMarkup, err error)

NewFileMarkup create new FileMarkup instance form file in "filePath". The "fi" option is optional, if its nil it will Stat-ed manually.

type ServeOptions

type ServeOptions struct {
	http.ServerOptions

	// IsDevelopment if set to true, it will serve the ConvertOptions.Root
	// directory directly and watch all asciidoc files for changes and
	// convert it.
	// This is like running Watch, Convert and Serve at the same time.
	IsDevelopment bool
}

ServeOptions define the options to use on Serve function. See git.sr.ht/~shulhan/pakakeh.go/lib/http.ServerOptions for more information.