diff options
| l--------- | README.adoc | 1 | ||||
| -rw-r--r-- | README.md (renamed from README) | 89 | ||||
| l--------- | _doc/README.adoc | 1 | ||||
| l--------- | _doc/README.md | 1 |
4 files changed, 43 insertions, 49 deletions
diff --git a/README.adoc b/README.adoc deleted file mode 120000 index 100b938..0000000 --- a/README.adoc +++ /dev/null @@ -1 +0,0 @@ -README
\ No newline at end of file @@ -1,51 +1,47 @@ -= Welcome to ciigo -:toc: -:sectanchors: -:sectlinks: -:repo_url:https://git.sr.ht/~shulhan/ciigo -:repo_doc_url:https://pkg.go.dev/git.sr.ht/~shulhan/ciigo +# Welcome to ciigo `ciigo` is a library and a program to write static web server with embedded files using -https://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc^] -https://www.markdownguide.org/[Markdown^] +[AsciiDoc](https://asciidoctor.org/docs/what-is-asciidoc/) +and +[Markdown](https://www.markdownguide.org/) markup format. -== ciigo as CLI +## ciigo as CLI ciigo as CLI can convert, generate, and/or serve a directory that contains markup files, as HTML files. -=== Usage +### Usage ----- +``` $ ciigo [-template <file>] [-exclude <regex>] convert <dir> ----- +``` Scan the "dir" recursively to find markup files (.adoc) and convert them into HTML files. The template "file" is optional, default to embedded HTML template. ----- +``` $ ciigo [-template <file>] [-exclude <regex>] [-out <file>] generate <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. ----- +``` $ 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 as library +## 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`. @@ -58,34 +54,34 @@ 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 ( @@ -109,23 +105,23 @@ func main() { 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 @@ -141,7 +137,7 @@ program will automatically generated the HTML file. Refresh the web browser to load the new generated file. -=== Deployment +### 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. @@ -149,7 +145,7 @@ 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 ( @@ -175,29 +171,29 @@ func main() { 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. @@ -207,24 +203,24 @@ If you need to use another port, you can change it at `cmd/mysite/main.go`. That's it! -== Limitations and known bugs +## Limitations and known bugs Using symlink on ".adoc" file inside Root directory that reference file outside of Root is not supported, yet. -== Links +## Links -{repo_url}[Ciigo repository^]. +[Ciigo repository](https://git.sr.ht/shulhan/ciigo). -{repo_doc_url}[Go module documentation^]. +[Go module +documentation](https://pkg.go.dev/git.sr.ht/https://git.sr.ht/shulhan/ciigoshulhan/ciigo). -== License +## 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 @@ -240,4 +236,3 @@ 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/>. ----- diff --git a/_doc/README.adoc b/_doc/README.adoc deleted file mode 120000 index a7ab0b1..0000000 --- a/_doc/README.adoc +++ /dev/null @@ -1 +0,0 @@ -../README.adoc
\ No newline at end of file diff --git a/_doc/README.md b/_doc/README.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/_doc/README.md @@ -0,0 +1 @@ +../README.md
\ No newline at end of file |