diff options
| -rw-r--r-- | README.md | 227 | ||||
| -rw-r--r-- | _example/.gitignore | 2 | ||||
| l--------- | _example/COPYING | 1 |
3 files changed, 212 insertions, 18 deletions
@@ -1,7 +1,7 @@ # Welcome to ciigo -`ciigo` is a library and a program to write static web server with embedded -files using +`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](https://asciidoctor.org/docs/what-is-asciidoc/) and [Markdown](https://www.markdownguide.org/) @@ -16,54 +16,247 @@ As showcase, the following websites are build using ciigo, [Source code](https://git.sr.ht/~shulhan/golang-id-web). +Features, + +* Simple. There is only five commands: convert, embed, help, serve, and + version. + +* No themes, built your own template and style. + Except for default + [HTML](https://git.sr.ht/~shulhan/ciigo/tree/main/item/template_index_html.go) + template and embedded + [CSS](https://git.sr.ht/~shulhan/ciigo/tree/main/item/embedded_css.go), + 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](https://go.dev/dl). + +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. -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. -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. -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". -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 "_example" directory that we can try using +`ciigo`. + +``` +$ tree _example +_example/ +├── custom.css +├── favicon.ico +├── html.tmpl +├── index.adoc +├── index.css +└── sub + └── index.adoc +``` + +First, lets convert all AsciiDoc files (.adoc) inside the "_example" +directory recursively, + +``` +$ ciigo convert ./_example +2025/01/06 19:17:07 convertFileMarkups: converting _example/sub/index.adoc +2025/01/06 19:17:07 convertFileMarkups: converting _example/index.adoc +$ +``` + +Then serve it under HTTP server, -Print the current ciigo version. +``` +$ ciigo serve ./_example/ +2025/01/06 19:17:47 ciigo: starting HTTP server at http://127.0.0.1:6320 for "./_example" + +``` + +While the program still running, open the +[http://127.0.0.1:6320](http://127.0.0.1:6320) in your +browser. +Notice that we have "sub" directory. +Lets open +[http://127.0.0.1:6320/sub/](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 _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 and run convert again. + +``` +$ touch _example/html.tmpl +$ ciigo -template ./_example/html.tmpl convert ./_example/ +2025/01/06 19:28:17 convertFileMarkups: converting _example/sub/index.adoc +2025/01/06 19:28:17 convertFileMarkups: converting _example/index.adoc +$ +``` + +Run the `serve` command again, +``` +$ ciigo serve ./_example/ +2025/01/06 19:36:07 ciigo: starting HTTP server at http://127.0.0.1:6320 for "./_example" + +``` +You can see now that the new template rendered, with "ciigo" in the top-left +and "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 _example directory, +``` +$ ciigo serve ./_example/ +2025/01/06 19:46:54 ciigo: starting HTTP server at http://127.0.0.1:6320 for "./_example" + +``` + +Create new directory "journal" under "_example", +``` +$ mkdir -p ./_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/](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. + +Another way to trigger ciigo to rescan for new markup files is by creating +or updating file ".ciigo_rescan" inside the content directory. +In the above example, by creating file "_example/.ciigo_rescan". + +Lets try updating the "journal/index.adoc" into +``` += My Journal + +Hello ciigo! +``` +and create or update the ".ciigo_rescan", +``` +$ touch _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 "_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 \ + _example/ \ + user@myserver:/srv/pub/ +``` ## ciigo as library @@ -223,7 +416,7 @@ $ ./mysite Finally, deploy the program to your server. NOTE: By default, server will listen on address `0.0.0.0` at port `8080`. -If you need to use another port, you can change it at `cmd/mysite/main.go`. +If we need to use another port, we can change it at `cmd/mysite/main.go`. That's it! diff --git a/_example/.gitignore b/_example/.gitignore new file mode 100644 index 0000000..ed8cb1d --- /dev/null +++ b/_example/.gitignore @@ -0,0 +1,2 @@ +/.ciigo_rescan +/journal diff --git a/_example/COPYING b/_example/COPYING deleted file mode 120000 index 012065c..0000000 --- a/_example/COPYING +++ /dev/null @@ -1 +0,0 @@ -../COPYING
\ No newline at end of file |