ciigo
is a library and a program to write static web server with embedded
files using
AsciiDoc
and
Markdown
markup format.
As showcase, the following websites are build using ciigo,
ciigo as CLI can convert, generate, and/or serve a directory that contains markup files, as HTML files.
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.
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!
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.
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 you need to use another port, you can change it at cmd/mysite/main.go
.
That's it!
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.
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 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. 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/.