all: rename the "content" directory to "_example"

While at it, also move the templates into _example and all assets into the same directory.
author: Shulhan <ms@kilabit.info> 2020-05-01 15:04:39 +0700
committer: Shulhan <ms@kilabit.info> 2020-05-07 13:56:46 +0700
commit: be40291e5dac2a56de940bfb5dfc842b856ca233 (patch)
tree: 2e1481b01939743d1492d6271069ccd7b9aefaf4 /_example
parent: 8713b9674b608dd2c7e95215d4b7e8a298898611 (diff)
download: ciigo-be40291e5dac2a56de940bfb5dfc842b856ca233.tar.xz
7 files changed, 443 insertions, 0 deletions
diff --git a/_example/LICENSE b/_example/LICENSE
new file mode 120000
index 0000000..ea5b606
--- /dev/null
+++ b/_example/LICENSE
@@ -0,0 +1 @@
+../LICENSE
+\ No newline at end of file
diff --git a/_example/custom.css b/_example/custom.css
new file mode 100644
index 0000000..6690ee7
--- /dev/null
+++ b/_example/custom.css
@@ -0,0 +1,3 @@
+h1 {
+	color: sienna;
+}
diff --git a/_example/favicon.ico b/_example/favicon.ico
new file mode 100644
index 0000000..8d22584
--- /dev/null
+++ b/_example/favicon.ico
diff --git a/_example/html.tmpl b/_example/html.tmpl
new file mode 100644
index 0000000..d5612c9
--- /dev/null
+++ b/_example/html.tmpl
@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="theme-color" content="#375EAB" />
+
+		<title>{{.Title}}</title>
+		<link rel="stylesheet" href="/index.css" />
+		{{- range .Styles}}
+		<link rel="stylesheet" href="{{.}}" />
+		{{- end}}
+	</head>
+	<body>
+		<div class="topbar">
+			<div class="container">
+				<div class="top-heading">
+					<a href="/">ciigo</a>
+				</div>
+				<div class="menu">
+					<form class="item" action="/_internal/search">
+						<input type="text" name="q" placeholder="Search" />
+					</form>
+				</div>
+				<div class="menu">
+					<a href="/sub">Sub</a>
+				</div>
+			</div>
+		</div>
+
+		<div class="page">
+			<div class="container">
+				<h1>{{.Title}}</h1>
+				<div class="meta">
+					{{.Author}}
+					<br />
+					{{.Date}}
+				</div>
+				{{.Body}}
+			</div>
+			<!-- .container -->
+		</div>
+		<!-- .page -->
+
+		<div class="footer">
+			Powered by <a
+				href="https://github.com/shuLhan/ciigo"
+			>
+				ciigo
+			</a>
+		</div>
+	</body>
+</html>
diff --git a/_example/index.adoc b/_example/index.adoc
new file mode 100644
index 0000000..81c3c9c
--- /dev/null
+++ b/_example/index.adoc
@@ -0,0 +1,221 @@
+=  Welcome to ciigo
+:author: Shulhan
+:date: 25 September 2019
+:url-gocard: https://goreportcard.com/report/github.com/shuLhan/ciigo
+:url-godoc: https://pkg.go.dev/github.com/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/github.com/shuLhan/ciigo[Go Report Card, link={url-gocard}]
+
+`ciigo` is a library and a program to write static web server with embedded
+files using generated markup format.
+
+Currently, ciigo support
+https://asciidoctor.org/docs/what-is-asciidoc/[asciidoc]
+and
+https://commonmark.org/[markdown]
+as markup format.
+
+
+==  ciigo as library
+
+For an up to date documentation of how to use the library see the 
+{url-godoc}[Go documentation page].
+
+
+==  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>] 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>] [-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/github.com/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/github.com/shuLhan/ciigo/_example/index.css ./_contents/
+$ cp $HOME/go/src/github.com/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 (
+        "github.com/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 (
+        "github.com/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` (or `.md`)
+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://github.com/shuLhan/ciigo
+under custom link:/LICENSE[BSD license].
+
+
+==  Credits
+
+This software is developed with helps from the following third party
+libraries,
+
+*  https://github.com/bytesparadise/libasciidoc[libasciidoc].
+   https://raw.githubusercontent.com/bytesparadise/libasciidoc/master/LICENSE[License].
+
+*  https://github.com/yuin/goldmark[goldmark].
+   https://raw.githubusercontent.com/yuin/goldmark/master/LICENSE[License].
diff --git a/_example/index.css b/_example/index.css
new file mode 100644
index 0000000..2168b46
--- /dev/null
+++ b/_example/index.css
@@ -0,0 +1,161 @@
+body {
+	margin: 0;
+	font-family: Arial, sans-serif;
+	background-color: #fff;
+	line-height: 1.3;
+	text-align: center;
+	color: #222;
+}
+pre {
+	font-family: Menlo, monospace;
+	font-size: 0.875rem;
+	line-height: 1.4;
+	overflow-x: auto;
+	background: #efefef;
+	padding: 0.625rem;
+	border-radius: 0.3125rem;
+}
+a {
+	color: #375eab;
+	text-decoration: none;
+}
+a:hover {
+	text-decoration: underline;
+}
+
+p,
+li {
+	max-width: 50rem;
+	word-wrap: break-word;
+}
+p,
+pre,
+ul,
+ol {
+	margin: 1.25rem;
+}
+
+h1,
+h2,
+h3,
+h4 {
+	margin: 1.25rem 0 1.25rem;
+	padding: 0;
+	color: #375eab;
+	font-weight: bold;
+}
+h1 {
+	font-size: 1.75rem;
+	line-height: 1;
+}
+h1 .text-muted {
+	color: #777;
+}
+h2 {
+	clear: right;
+	font-size: 1.25rem;
+	background: #e0ebf5;
+	padding: 0.5rem;
+	line-height: 1.25;
+	font-weight: normal;
+	overflow: auto;
+	overflow-wrap: break-word;
+}
+h2 a {
+	font-weight: bold;
+}
+h3 {
+	font-size: 1.25rem;
+	line-height: 1.25;
+	overflow: auto;
+	overflow-wrap: break-word;
+}
+h3,
+h4 {
+	margin: 1.25rem 0.3125rem;
+}
+h4 {
+	font-size: 1rem;
+}
+
+h2 > span,
+h3 > span {
+	float: right;
+	margin: 0 25px 0 0;
+	font-weight: normal;
+	color: #5279c7;
+}
+
+dl {
+	margin: 1.25rem;
+}
+dd {
+	margin: 0 0 0 1.25rem;
+}
+dl,
+dd {
+	font-size: 0.875rem;
+}
+
+/**
+ * Custom classes for pages
+ */
+
+.topbar {
+	background: #e0ebf5;
+	height: 4rem;
+	overflow: hidden;
+}
+
+.topbar .top-heading,
+.topbar .menu {
+	padding: 1.313rem 0;
+	font-size: 1.25rem;
+	font-weight: normal;
+}
+
+.topbar .top-heading {
+	float: left;
+}
+.topbar .top-heading a {
+	color: #222;
+	text-decoration: none;
+}
+
+.topbar .menu {
+	float: right;
+}
+.topbar .menu a {
+	margin: 0.625rem 0.125rem;
+	padding: 0.625rem;
+	color: white;
+	background: #375eab;
+	border: 0.0625rem solid #375eab;
+	border-radius: 5px;
+}
+.topbar .menu form {
+	margin-left: 0.625rem;
+}
+.page {
+	width: 100%;
+}
+
+.page > .container,
+.topbar > .container {
+	text-align: left;
+	margin-left: auto;
+	margin-right: auto;
+	padding: 0 1.25rem;
+}
+
+.container .meta {
+	font-style: italic;
+	margin: 1.25rem;
+}
+
+.footer {
+	text-align: center;
+	color: #666;
+	font-size: 0.875rem;
+	margin: 2.5rem 0;
+}
diff --git a/_example/sub/index.adoc b/_example/sub/index.adoc
new file mode 100644
index 0000000..e605902
--- /dev/null
+++ b/_example/sub/index.adoc
@@ -0,0 +1,4 @@
+= Sub directory
+:stylesheet: /custom.css
+
+This is an example of content in sub directory using custom stylesheet.
author	Shulhan <ms@kilabit.info>	2020-05-01 15:04:39 +0700
committer	Shulhan <ms@kilabit.info>	2020-05-07 13:56:46 +0700
commit	be40291e5dac2a56de940bfb5dfc842b856ca233 (patch)
tree	2e1481b01939743d1492d6271069ccd7b9aefaf4 /_example
parent	8713b9674b608dd2c7e95215d4b7e8a298898611 (diff)
download	ciigo-be40291e5dac2a56de940bfb5dfc842b856ca233.tar.xz