all: group all documents under directory _doc

5 files changed, 269 insertions, 243 deletions

diff --git a/README b/README
index bff755a..df2fae8 120000..100644
--- a/README
+++ b/README
@@ -1 +1,242 @@
-README.adoc
\ No newline at end of file
+=  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
+
+`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 CLI
+
+ciigo as CLI can convert, generate, and/or serve a directory that contains
+markup files, as HTML files.
+
+===  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
+
+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"
+	"github.com/shuLhan/share/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.
+
+
+===  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 you need to use another port, you can change it at `cmd/mysite/main.go`.
+
+That's it!
+
+
+==  Limitations and known bugs
+
+Using symlink on ".adoc" file inside Root directory that reference file
+outside of Root is not supported, yet.
+
+
+==  Links
+
+{repo_url}[Ciigo repository^].
+
+{repo_doc_url}[Go module documentation^].
+
+
+==  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 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/>.
+----
diff --git a/README.adoc b/README.adoc
index df2fae8..100b938 100644..120000
--- a/README.adoc
+++ b/README.adoc
@@ -1,242 +1 @@
-=  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
-
-`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 CLI
-
-ciigo as CLI can convert, generate, and/or serve a directory that contains
-markup files, as HTML files.
-
-===  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
-
-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"
-	"github.com/shuLhan/share/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.
-
-
-===  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 you need to use another port, you can change it at `cmd/mysite/main.go`.
-
-That's it!
-
-
-==  Limitations and known bugs
-
-Using symlink on ".adoc" file inside Root directory that reference file
-outside of Root is not supported, yet.
-
-
-==  Links
-
-{repo_url}[Ciigo repository^].
-
-{repo_doc_url}[Go module documentation^].
-
-
-==  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 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/>.
-----
+README
\ No newline at end of file
diff --git a/CHANGELOG.adoc b/_doc/CHANGELOG.adoc
index 2f91ad0..2f91ad0 100644
--- a/CHANGELOG.adoc
+++ b/_doc/CHANGELOG.adoc
diff --git a/_doc/README.adoc b/_doc/README.adoc
new file mode 120000
index 0000000..a7ab0b1
--- /dev/null
+++ b/_doc/README.adoc
@@ -0,0 +1 @@
+../README.adoc
\ No newline at end of file
diff --git a/_doc/index.adoc b/_doc/index.adoc
new file mode 100644
index 0000000..1d7c3f5
--- /dev/null
+++ b/_doc/index.adoc
@@ -0,0 +1,25 @@
+= ciigo
+:toc:
+:sectanchors:
+:sectlinks:
+
+Welcome to ciigo.
+
+ciigo is a library and a program to write static web server with embedded
+files using AsciiDoc markup format.
+
+==  Documentation
+
+link:CHANGELOG.html[CHANGELOG^]:: History of each release.
+
+link:README.html[README^]:: User manual page for ciigo.
+
+==  Development
+
+https://git.sr.ht/~shulhan/ciigo[Repository^]:: Link to the source code.
+
+https://lists.sr.ht/~shulhan/ciigo[Mailing list^]:: Link to development and
+discussion.
+
+https://todo.sr.ht/~shulhan/ciigo[Issues^]:: Link to submit an issue,
+feedback, or request for new feature.