README: reformat to markdown to make it readable by sourcehut

While at it simplify the example of index.adoc.

1 files changed, 5 insertions, 189 deletions

diff --git a/_example/index.adoc b/_example/index.adoc
index c448168..b59527b 100644
--- a/_example/index.adoc
+++ b/_example/index.adoc
@@ -1,205 +1,21 @@
 =  Welcome to ciigo
-:author: Shulhan
-:date: 25 September 2019
-:url-gocard: https://goreportcard.com/report/git.sr.ht/~shulhan/ciigo
+Shulhan <ms@kilabit.info>
+25 September 2019
 :url-godoc: https://pkg.go.dev/git.sr.ht/~shulhan/ciigo
 
 image:https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square[GoDoc, link={url-godoc}]
-image:https://goreportcard.com/badge/git.sr.ht/~shulhan/ciigo[Go Report Card, link={url-gocard}]
 
 `ciigo` is a library and a program to write static web server with embedded
 files using
 https://asciidoctor.org/docs/what-is-asciidoc/[asciidoc]
 markup format.
 
-
 ==  ciigo as library
 
-For an up to date documentation of how to use the library see the 
-{url-godoc}[Go documentation page].
-
+For an up to date documentation of how to use the library see the
+https://pkg.go.dev/git.sr.ht/~shulhan/ciigo[Go documentation page].
 
 ==  ciigo as CLI
 
-ciigo as CLI can convert, generate, and/or serve a directory that contains
+`ciigo` as CLI can convert, generate, and/or serve a directory that contains
 markup files, as HTML files.
-
-===  Usage
-
-----
-$ ciigo [-template <file>] 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>] [-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>] [-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".
-
-
-==  Example
-
-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 a Go source code in the root repository to generate all markup files
-inside the "_contents" directory into HTML and dump all of their contents into
-"static.go" file.
-Lets named it `generate.go` with the following content,
-
-----
-//go:generate go run generate.go
-
-package main
-
-import (
-        "git.sr.ht/~shulhan/ciigo"
-)
-
-func main() {
-        ciigo.Generate("./_contents", "cmd/mysite/static.go", "_contents/html.tmpl")
-}
-----
-
-Create the main Go code inside `cmd/mysite`,
-
-----
-package main
-
-import (
-        "git.sr.ht/~shulhan/ciigo"
-)
-
-func main() {
-        ciigo.Serve("./_contents", ":8080", "_contents/html.tmpl")
-}
-----
-
-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
-:stylesheet: /_contents/index.css
-
-Hello, world!
-----
-
-Run `go generate` to convert all files with extension `.adoc`
-into HTML and embed it into `./cmd/mysite/static.go`
-
-----
-$ go generate
-----
-
-Now run the `./cmd/mysite` with `DEBUG` environment variable is set,
-
-----
-$ 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" or ",md" files inside "_contents" directory, the
-program will automatically generated the HTML file, but you still need to
-refresh the web browser to load the new generated file.
-
-
-===  Deployment
-
-First, we need to make sure that all markup files inside "_contents" are
-converted to HTML and regenerate the static Go code,
-
-----
-$ go generate
-----
-
-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`.
-
-
-
-==  Limitations and Known Bugs
-
-`ciigo` will not handle automatic certificate (e.g. using LetsEncrypt), its
-up to administrator how the certificate are gathered or generated.
-
-Using symlink on ".adoc" file inside `content` directory is not supported yet.
-
-
-==  Resources
-
-The source code for this software can be viewed at
-https://git.sr.ht/~shulhan/ciigo
-under custom link:/LICENSE[BSD license].