Skip to content
Go static website generator with asciidoc markup language
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/ciigo
content
templates
.gitignore
LICENSE
Makefile
README.adoc
ciigo.go
fileadoc.go
filehtml.go
generate.go
generate_main.go
go.mod
go.sum
htmlgenerator.go
server.go

README.adoc

Welcome to ciigo

ciigo is a program to write static web server with embedded files using asciidoc markup language.

Document Structure

This software use the following directory structure and file name conventions,

  • cmd/<name>: this is the program that serve the generated content.

  • content: the root directory of static and generated content to be embedded and served. This is where asciidoc files must be saved. Any files inside this directory (except in "content/assets") will be ignored.

  • content/assets: contains static files (images, js, css) that can be accessed by any pages using absolute path under /assets/.

  • templates: contains dynamic templates. Currently. there is only single template: html.tmpl, that wrap the generated HTML.

  • All asciidoc files inside content must have an ".adoc" extension.

Getting Started

This section describe step by step instructions on how to build and create pages to be viewed for local development using ciigo.

  1. Clone the ciigo repository. For example, lets say we have clone the ciigo repository into $HOME/go/src/github.com/shuLhan/ciigo.

  2. 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
  3. If you use Go module, create the Go module; if you use GOPATH ignore this step.

    $ go mod init remote.tld/user/mysite
  4. Create directories for storing our content and a package binary. ciigo use strict directory structure as we have mention above.

    $ mkdir -p cmd/mysite
    $ mkdir -p content/assets
    $ mkdir -p templates
  5. Copy the example of stylesheet and HTML template from ciigo repository,

    $ cp $HOME/go/src/github.com/shuLhan/ciigo/content/assets/style.css ./content/assets/
    $ cp $HOME/go/src/github.com/shuLhan/ciigo/templates/html.tmpl ./templates/
  6. Create a Go source code to generate all asciidoc files inside "content" directory. 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("./content", "cmd/mysite/static.go")
    }
  7. Create the main Go code inside cmd/mysite,

    package main
    
    import (
            "github.com/shuLhan/ciigo"
    )
    
    func main() {
            srv := ciigo.NewServer(":8080")
    
            srv.Start()
    }
  8. Create a new asciidoc file index.adoc inside "content" directory. Each directory, or sub directory, should have index.adoc to be able to accessed by browser,

    =  Test
    :stylesheet: /assets/style.css
    
    Hello, world!
  9. Build the binary on local directory with DEBUG environment variable is set,

    $ export DEBUG=1
    $ go build ./cmd/mysite

    Any non zero value on DEBUG environment signal the running program to watch changes in ".adoc" files inside "content" directory and serve the generated HTML directly.

  10. Run the mysite binary on current directory,

    $ ./mysite
  11. 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 in "content" directory, the program will automatically generated the HTML file.

Deployment

First, we need to convert all asciidoc files inside "content" into HTML and dump the content of all static files inside "content",

$ go generate

The above command will generate Go source code in cmd/mystite/static.go.

Second, build the web server that serve static contents in static.go,

$ go build cmd/ciigo

Third, test the web server by running the program and opening localhost:8080 on web browser,

$ ./ciigo

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 BSD license.

Credits

This software is developed with helps from third party libraries. The following section list only direct third party library.

You can’t perform that action at this time.