diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 223 |
1 files changed, 49 insertions, 174 deletions
@@ -1,4 +1,5 @@ # 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 @@ -18,8 +19,8 @@ As showcase, the following websites are build using ciigo, Features, -* Simple. There is only five commands: convert, embed, help, serve, and - version. +* Simple. There is only three main commands: `convert`, `embed`, and + `serve`. * No themes, built your own template and style. Except for default @@ -34,14 +35,15 @@ Features, 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 +### Installation +<!--{{{--> The installation require the `git` and Go tools which you can download it [here](https://go.dev/dl). @@ -67,8 +69,9 @@ If you did not know where `$GOBIN` is, run "go env" and check for `GOBIN` environment variable. It usually in `$HOME/go/bin`. - -### Usage +<!--}}}--> +### Usage +<!--{{{--> ``` ciigo [-template <file>] [-exclude <regex>] convert <dir> @@ -111,8 +114,9 @@ ciigo version ``` > Print the current ciigo version. - +<!--}}}--> ### Example +<!--{{{--> In this repository, we have an "_example" directory that we can try using `ciigo`. @@ -171,27 +175,37 @@ $ 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. +our template file, ``` $ touch _example/html.tmpl +$ +``` +or delete all the HTML files, +``` +$ find _example/ -name "*.html" -delete +$ +``` +and then run the convert command again. +``` $ 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, +Run the `serve` command again to preview our new generated HTML files, ``` $ 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. - +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. @@ -241,8 +255,9 @@ $ ``` 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. @@ -258,170 +273,27 @@ $ rsync --exclude='.*' \ user@myserver:/srv/pub/ ``` +<!--}}}--> ## ciigo as library +<!--{{{--> -This section describe step by step instructions on how to build and create -pages to be viewed for local development using `ciigo`. - -First, clone the `ciigo` repository. -Let says that we have cloned the `ciigo` repository into -`$HOME/go/src/git.sr.ht/~shulhan/ciigo`. - -Create new Go repository for building a website. -For example, in directory `$HOME/go/src/remote.tld/user/mysite`. -Replace "remote.tld/user/mysite" with your private or public repository. - -``` -$ mkdir -p $HOME/go/src/remote.tld/user/mysite -$ cd $HOME/go/src/remote.tld/user/mysite -``` - -Initialize the Go module, - -``` -$ go mod init remote.tld/user/mysite -``` - -Create directories for storing our content and a package binary. - -``` -$ mkdir -p cmd/mysite -$ mkdir -p _contents -``` - -Copy the example of stylesheet and HTML template from `ciigo` repository, - -``` -$ cp $HOME/go/src/git.sr.ht/~shulhan/ciigo/_example/index.css ./_contents/ -$ cp $HOME/go/src/git.sr.ht/~shulhan/ciigo/_example/html.tmpl ./_contents/ -``` - -Create the main Go code inside `cmd/mysite`, - -``` -package main - -import ( - "git.sr.ht/~shulhan/ciigo" - "git.sr.ht/~shulhan/pakakeh.go/lib/memfs" -) - -var mysiteFS *memfs.MemFS - -func main() { - opts := &ciigo.ServeOptions{ - ConvertOptions: ciigo.ConvertOptions{ - Root: "_contents", - HtmlTemplate: "_contents/html.tmpl", - }, - Address: ":8080", - Mfs: mysiteFS, - } - err := ciigo.Serve(opts) - if err != nil { - log.Fatal(err) - } -} -``` - -Create a new markup file `index.adoc` inside the "_contents" directory. -Each directory, or sub directory, should have `index.adoc` to be able to -accessed by browser, - -``` -= Test - -Hello, world! -``` - -Now run the `./cmd/mysite` with `DEBUG` environment variable set to non-zero, - -``` -$ DEBUG=1 go run ./cmd/mysite -``` - -Any non zero value on `DEBUG` environment signal the running program to watch -changes in ".adoc" files inside "_contents" directory and serve the generated -HTML directly. - -Open the web browser at `localhost:8080` to view the generated HTML. -You should see "Hello, world!" as the main page. - -Thats it! +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. -Create or update any ".adoc" files inside "_contents" directory, the -program will automatically generated the HTML file. -Refresh the web browser to load the new generated file. +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](https://git.sr.ht/~shulhan/ciigo/tree/main/internal/cmd/ciigo-example). -### Deployment - -First, we need to make sure that all markup files inside "_contents" are -converted to HTML and embed it into the static Go code. - -Create another Go source code, lets save it in `internal/generate.go` with the -following content, - -``` -package main - -import ( - "log" - - "git.sr.ht/~shulhan/ciigo" -) - -func main() { - opts := &ciigo.EmbedOptions{ - ConvertOptions: ciigo.ConvertOptions{ - Root: "_contents", - HtmlTemplate: "_contents/html.tmpl", - }, - EmbedOptions: memfs.EmbedOptions{ - PackageName: "main", - VarName: "mysiteFS", - GoFileName: "cmd/mysite/static.go", - }, - } - err := ciigo.GoEmbed(opts) - if err != nil { - log.Fatal(err) - } -} -``` - -And then run, - -``` -$ go run ./internal -``` - -The above command will generate Go source code `cmd/mysite/static.go` that -embed all files inside the "_contents" directory. - -Second, build the web server that serve static contents in `static.go`, - -``` -$ go build cmd/mysite -``` - -Third, test the web server by running the program and opening `localhost:8080` -on web browser, - -``` -$ ./mysite -``` - -Finally, deploy the program to your server. - -NOTE: By default, server will listen on address `0.0.0.0` at port `8080`. -If we need to use another port, we can change it at `cmd/mysite/main.go`. - -That's it! +That's it, happy writing! +<!--}}}--> ## Links +<!--{{{--> <https://git.sr.ht/~shulhan/ciigo> - Link to the source code. @@ -434,23 +306,26 @@ request for new feature. [Change log](/CHANGELOG.html) - Log of each releases. - +<!--}}}--> ## License +<!--{{{--> This software is licensed under GPL 3.0 or later. Copyright 2022 Shulhan <ms@kilabit.info> -This program is free software: you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation, either version 3 of the License, or (at your option) any later -version. +This program is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) +any later version. This program is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -FOR A PARTICULAR PURPOSE. +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. + +<!--}}}--> |