diff --git a/docs/README.md b/en-US/docs/README.md similarity index 99% rename from docs/README.md rename to en-US/docs/README.md index 1b5829b..e923257 100644 --- a/docs/README.md +++ b/en-US/docs/README.md @@ -228,7 +228,7 @@ Upload `public` to your server. GitHub Actions workflow configuration can be found in [Get Started](https://github.com/webpagine/get-started) repository. -# FAQ +## FAQ ### Why another generator? Isn't Hugo enough? diff --git a/docs/unit.toml b/en-US/docs/unit.toml similarity index 100% rename from docs/unit.toml rename to en-US/docs/unit.toml diff --git a/mainpage.html b/en-US/mainpage.html similarity index 95% rename from mainpage.html rename to en-US/mainpage.html index 787400c..46153b5 100644 --- a/mainpage.html +++ b/en-US/mainpage.html @@ -1,4 +1,6 @@ -
+
+ +
logo @@ -8,11 +10,12 @@ GET STARTED WITH PAGINE VIEW SOURCE CODE
-
GitHub Repo stars
+
+ {{ define "flip" }} {{ if . }} class="section-filled" style="text-align: left" {{ else }} style="text-align: right" {{ end }} {{ end }} diff --git a/en-US/unit.toml b/en-US/unit.toml new file mode 100644 index 0000000..a6bf92d --- /dev/null +++ b/en-US/unit.toml @@ -0,0 +1,4 @@ +[[unit]] +template = "genesis:page" +output = "/index.html" +define = { title = "Pagine - Web Generator", content = "/mainpage.html" } diff --git a/metadata.toml b/metadata.toml index b99b7e1..dbf746a 100644 --- a/metadata.toml +++ b/metadata.toml @@ -1,7 +1,16 @@ [genesis] lang = "en" +locale = "en-US" theme = "dark" +[[genesis.locales]] +locale = "en-US" +title = "English" + +[[genesis.locales]] +locale = "zh-CN" +title = "简体中文" + [genesis.head] icon = "https://avatars.githubusercontent.com/u/168826426" diff --git a/templates/genesis b/templates/genesis index c3c4b62..89c8865 160000 --- a/templates/genesis +++ b/templates/genesis @@ -1 +1 @@ -Subproject commit c3c4b62fc6ae8b1fe84353eb1dda16793fcae643 +Subproject commit 89c88651ed338f78e79b9f89bd09e17b7c8532d4 diff --git a/unit.toml b/unit.toml index ae19a2e..27f9a37 100644 --- a/unit.toml +++ b/unit.toml @@ -1,7 +1,7 @@ [[unit]] -template = "genesis:page" +template = "genesis:locale" output = "/index.html" -define = { title = "Pagine - Web Generator", content = "/mainpage.html" } +define = { title = "Pagine - Web Generator" } [[unit]] template = "genesis:page" diff --git a/zh-CN/docs/README.md b/zh-CN/docs/README.md new file mode 100644 index 0000000..e923257 --- /dev/null +++ b/zh-CN/docs/README.md @@ -0,0 +1,269 @@ +# Pagine v2 + +Pagine is an high-performance website constructor that makes full use of multicore hardware. + +Build jobs can be completed very fast. + +## Features + +- Parallel hierarchy processing and unit execution. Everything is executed in parallel from beginning to end. +- Hierarchical metadata propagation which makes metadata management easy. +- Manage templates and assets via Git. Every template can be distributed and used without modification. +- In-template builtin functions +- Interact with Pagine in templates. +- Update on file change while running as HTTP server. + +Supported rich text formats: + +- [Markdown](https://markdownguide.org) with [MathJax](https://www.mathjax.org) support +- [Asciidoc](https://asciidoc.org) + +## Install + +### Binaries + +Find the executable that matches your OS and architecture in [releases](https://github.com/webpagine/pagine/v2/releases). + +### Build from source + +```shell +$ go install github.com/webpagine/pagine/v2/cmd/pagine@latest +``` + +## Usage + +Usage of pagine: +- `-public` string + - Location of public directory. (default `/tmp/$(basename $PWD).public`) +- `-root` string + - Site root. (default `$PWD`) +- `-serve` string + - Specify the port to listen and serve as HTTP. + + +### Generate + +```shell +$ cd ~/web/my_site +$ pagine +Generation complete. +``` + +### Run as HTTP server + +```shell +$ cd ~/web/my_site +$ pagine --serve :12450 +``` + +It automatically executes generation when file changes are detected by `inotify`. + +> [!NOTE] +> Incremental generation is not implemented yet.
+> Set the `--public` under `/tmp` is recommended to reduce hard disk writes. + +Since v2.1.0, the server provides a WebSocket interface at `/ws` to provide event monitoring for the client, such as page updates. + +## Structure + +### Template + +Template is a set of page frames (Go template file) and assets (e.g. SVGs, stylesheets and scripts). + +Manifest of one template looks like: +```toml +[manifest] +canonical = "com.symboltics.pagine.genesis" # Canonical name +patterns = [ "/*html" ] # Matched files will be added as template file. + +[[templates]] +name = "page" # Export as name `page` +export = "page.html" # Export `page.html` + +[[templates]] +name = "post" # Export as name `post` +export = "post.html" # Export `post.html` +``` + +To the Go templates files syntax, see [text/template](https://pkg.go.dev/text/template). + +Example: `page.html` +```html + + + {{ .title }} + + + +{{ template "header.html" .header }} +
{{ render .content }}
+ +{{ template "footer.html" .footer }} + +``` + +### Env + +"Environment" is the configuration of the details of the entire process. + +```toml +ignore = [ "/.git*" ] # Pattern matching. Matched files will not be **copied** to the public/destination. + +[use] +genesis = "/templates/genesis" +another = "/templates/something_else" # Load and set alias for the template. +``` + +Installing templates via Git submodule is recommended. Such as: + +```shell +$ git submodule add https://github.com/webpagine/genesis templates/genesis +``` + +### Level + +Each "level" contains its metadata. And a set of units to be executed. + +For directories, metadata sets are stored in `metadata.toml` in the form of map, and units are stored in `unit.toml` + +Each template has its alias that defined in `env` as the namespace. + +Levels can override fields propagated from parents. + +Example: `/metadata.toml` +```toml +[genesis] +title = "Pagine" + +[genesis.head] +icon = "/favicon.ico" + +[[genesis.header.nav.items]] +name = "Documentation" +link = "/docs/" +``` + +### Unit + +Example: `/unit.toml` +```toml +[[unit]] +template = "genesis:page" # Which template to use. +output = "/index.html" # Where to save the result. +define = { title = "Pagine" } # Unit-specified metadata. + +[[unit]] +template = "genesis:page" +output = "/404.html" +define = { title = "Page not found" } +``` + +## Builtin functions + +### Arithmetic + +| Func | Args | Result | +|-------|-----------|--------| +| `add` | a, b: Int | Int | +| `sub` | a, b: Int | Int | +| `mul` | a, b: Int | Int | +| `div` | a, b: Int | Int | +| `mod` | a,b : Int | Int | + +### Engine API + +| Func | Args | Description | +|-----------|------------------------|--------------------------------------------------------------------------------------------------| +| `getAttr` | key: String | Get meta information in the form of map about units, hierarchy and templates provided by engine. | + +| Attribution | Description | +|----------------|-------------------------------------------------| +| `unitBase` | Unit's level's base dir path. | +| `templateBase` | It tells the template where it has been stored. | + +| Func | Description | +|---------------|-------------------------------------------------------| +| `getMetadata` | It returns the root node of metadata of the template. | + +### Data processing + +| Func | Args | Result | +|--------------|-----------------------------|--------| +| `hasPrefix` | str: String, prefix: String | Bool | +| `trimPrefix` | str: String, prefix: String | String | + +| Func | Args | Result | Description | +|------------------|-------------------------------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------| +| `divideSliceByN` | slice: []Any, n: Int | [][]Any | Divide a slice into *len(slice) / N* slices | +| `mapAsSlice` | map: map[String]Any, **key**, **value**: String | []map[String]{ **key**: String, **value**: Any } | Convert map to a slice of map that contains two keys named **key** and **value**. | + +### Content + +Path starts from where the unit is. + +| Func | Args | Description | +|------------------|------------------------|-----------------------------------------| +| `apply` | path: String, data Any | Invoke a template. | +| `embed` | path: String | Embed file raw content. | +| `render` | path: String | Invoke renderer by file extension name. | +| `renderAsciidoc` | path: String | Render and embed Asciidoc content. | +| `renderMarkdown` | path: String | Render and embed Markdown content. | + +| Format | File Extension Name | +|----------|---------------------| +| Markdown | `md` | +| Asciidoc | `adoc` | + +## Deploy + +### Manually + +```shell +$ pagine --public ../public +``` + +Upload `public` to your server. + +### Deploy to GitHub Pages via GitHub Actions (recommended) + +GitHub Actions workflow configuration can be found in [Get Started](https://github.com/webpagine/get-started) repository. + +## FAQ + +### Why another generator? Isn't Hugo enough? + +Pagine is **not** Hugo, and is not aim to replace Hugo. + +Pagine does not embed page configurations in Markdown file, they are separated and should be separated. + +And Pagine does not focus on Markdown only, I hope to support various kinds of source. + +### Can I use Pagine for building complex web application? + +It can only help you get rid of repetitive work about static contents. + +Templates can increase productivity as long as Pagine well integrated with external tools. + +So, **it depends**. + +### Co-operate with external tools such as npx? + +It is possible. This step should be transparent to external tools. + +Run `npx` in *public* directory after the generation by Pagine. + +### What is the origin of the logo and name? + +It is **neither** a browser engine, a layout engine **nor** a rendering engine. + +Page Gen × Engine ⇒ Pagine. It has similar pronunciation to "pagen". + +The logo is an opened book with a bookmark. + +### Rewrite it in other PL? + +*I expected somebody would ask.* + +It will not be taken unless it does bring obvious advantages. + +Thus: NO. It is not planned currently. diff --git a/zh-CN/docs/unit.toml b/zh-CN/docs/unit.toml new file mode 100644 index 0000000..3b46a33 --- /dev/null +++ b/zh-CN/docs/unit.toml @@ -0,0 +1,4 @@ +[[unit]] +template = "genesis:doc" +output = "/index.html" +define = { title = "Documentation", post = "/README.md" } diff --git a/zh-CN/mainpage.html b/zh-CN/mainpage.html new file mode 100644 index 0000000..46153b5 --- /dev/null +++ b/zh-CN/mainpage.html @@ -0,0 +1,72 @@ +
+ +
+
+ +logo +

Quickly build web content with frames from templates.
Just in milliseconds.

+ +
+GET STARTED WITH PAGINE +VIEW SOURCE CODE +
+
+GitHub Repo stars +
+ +
+ +{{ define "flip" }} +{{ if . }} class="section-filled" style="text-align: left" {{ else }} style="text-align: right" {{ end }} +{{ end }} + +{{ $flip := false }} + +{{ $flip = not $flip }} +
+

Everything, speed up!

+

+Make max of performance. Execute units and generate related pages in parallel.
+Flexibility without compromising efficiency. Do its job well. +

+
+ +{{ $flip = not $flip }} +
+

Creativity, inspired.

+Stylesheets, SVGs, interaction scripts... Make your own template,
+distribute and reuse template files via Git, with assets attached.
+Choose a license and publish your template, just in minutes! +
+ +{{ $flip = not $flip }} +
+

Internationalization, united!

+Write and translate your knowledge and experiences, share with the people around the world.
+Commit translation for articles you think is valuable, break the boundary of knowledge! +
+ +{{ $flip = not $flip }} +
+

Deployment, unattended.

+Well integrated with CD/CD services. You have never to worry about what to do after you wrote.
+Automatically update the page in server mode, see changes in real time.
+When you think everything is ready, deploy via CI/CD directly!
+For GitHub Pages, just an Actions workflow! +
+ +{{ $flip = not $flip }} +
+

Build what you want.

+Documentation, blog, wiki, encyclopedia ... Find your template, and start with it.
+Content, appearance and metadata are separated, which keeps the directories clear. +
+ +
+

Leave footprints on your journey.

+
+GET STARTED WITH PAGINE +
+
+ +
diff --git a/zh-CN/metadata.toml b/zh-CN/metadata.toml new file mode 100644 index 0000000..df4b141 --- /dev/null +++ b/zh-CN/metadata.toml @@ -0,0 +1,15 @@ +[genesis] +lang = "zh" +locale = "zh-CN" + +[genesis.header.nav.logo] +src = "/assets/img/pagine.svg" +height = 50 + +[[genesis.header.nav.items]] +title = "文档" +link = "/docs/" + +[[genesis.header.nav.items]] +title = "代码库" +link = "https://github.com/webpagine" diff --git a/zh-CN/unit.toml b/zh-CN/unit.toml new file mode 100644 index 0000000..a6bf92d --- /dev/null +++ b/zh-CN/unit.toml @@ -0,0 +1,4 @@ +[[unit]] +template = "genesis:page" +output = "/index.html" +define = { title = "Pagine - Web Generator", content = "/mainpage.html" }