aboutsummaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2026-01-02 13:56:47 -0500
committerEugene Triguba <hello@eugenetriguba.com>2026-01-02 13:56:47 -0500
commit85bde1cc6969e7db0aaab0851f6051350b30409f (patch)
treed1a6f0d196397bd06b9c603b4fe0d2bbdd665c18 /man
parentFix man page headings and use YYYY-MM-DD for dates (diff)
downloadssg-85bde1cc6969e7db0aaab0851f6051350b30409f.zip
Rewrite man pages in mdoc(7) format instead of older man(7) format
Diffstat (limited to 'man')
-rw-r--r--man/ssg-build.199
-rw-r--r--man/ssg-help.165
-rw-r--r--man/ssg-init.1100
-rw-r--r--man/ssg-serve.191
-rw-r--r--man/ssg-templates.5131
-rw-r--r--man/ssg-version.134
-rw-r--r--man/ssg.1104
7 files changed, 333 insertions, 291 deletions
diff --git a/man/ssg-build.1 b/man/ssg-build.1
index 231d1ae..83e09ee 100644
--- a/man/ssg-build.1
+++ b/man/ssg-build.1
@@ -1,59 +1,56 @@
-.TH SSG-BUILD 1 "2026-01-01" "ssg" "General Commands Manual"
-.SH NAME
-ssg-build \- build the site
-.SH SYNOPSIS
-.B ssg build
-.RI [ options ]
-.SH DESCRIPTION
-Build the static site by rendering templates with data and copying static files.
-.PP
-Templates are processed using Go's html/template package. See
-.BR ssg-templates (5)
+.Dd January 2, 2026
+.Dt SSG-BUILD 1
+.Os
+.Sh NAME
+.Nm ssg-build
+.Nd build the site
+.Sh SYNOPSIS
+.Nm ssg build
+.Op Fl h | -help
+.Op Fl d | -data Ar dir
+.Op Fl t | -templates Ar dir
+.Op Fl s | -static Ar dir
+.Op Fl o | -out Ar dir
+.Op Fl q | -quiet
+.Sh DESCRIPTION
+.Nm
+builds the static site by rendering HTML templates with the provided data into
+the output directory and copying static files to the output directory.
+.Pp
+Templates are processed using Go's
+.Lk https://pkg.go.dev/html/template html/template
+package. See
+.Xr ssg-templates 5
for template syntax and available functions.
-.SH OPTIONS
-.TP
-.BI \-data " dir"
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl h , Fl -help
+Print brief usage information.
+.It Fl d Ar dir , Fl -data Ar dir
Data directory containing JSON files. Default: data
-.TP
-.BI \-templates " dir"
+.It Fl t Ar dir , Fl -templates Ar dir
Templates directory containing HTML files. Default: templates
-.TP
-.BI \-static " dir"
+.It Fl s Ar dir , Fl -static Ar dir
Static files directory. Default: static
-.TP
-.BI \-out " dir"
+.It Fl o Ar dir , Fl -out Ar dir
Output directory. Default: dist
-.TP
-.B \-q
+.It Fl q , Fl -quiet
Quiet mode. Only show errors.
-.SH EXAMPLES
+.El
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and >0 if an error occurs.
+.Sh EXAMPLES
Build a site:
-.PP
-.RS
-.nf
-$ ssg build
-.fi
-.RE
-.PP
-Build to a custom output directory:
-.PP
-.RS
-.nf
-$ ssg build -out=public
-.fi
-.RE
-.PP
+.Dl $ ssg build
+.Pp
Build with custom directories:
-.PP
-.RS
-.nf
-$ ssg build -data=content -templates=layouts -out=public
-.fi
-.RE
-.SH SEE ALSO
-.BR ssg-templates (5),
-.BR ssg-serve (1)
-.SH SSG
-Part of the
-.BR ssg (1)
-suite.
+.Dl $ ssg build --static assets --data content --templates layouts --out public
+.Pp
+Build with regular output silenced:
+.Dl $ ssg build --quiet
+.Pp
+.Sh SEE ALSO
+.Xr ssg 1 ,
+.Xr ssg-serve 1 ,
+.Xr ssg-templates 5
diff --git a/man/ssg-help.1 b/man/ssg-help.1
index 0862cc2..5c241a1 100644
--- a/man/ssg-help.1
+++ b/man/ssg-help.1
@@ -1,32 +1,37 @@
-.TH SSG-HELP 1 "2026-01-01" "ssg" "General Commands Manual"
-.SH NAME
-ssg-help \- show manual page
-.SH SYNOPSIS
-.B ssg help
-.RI [ command ]
-.SH DESCRIPTION
-Open the manual page for a command.
-.PP
+.Dd January 2, 2026
+.Dt SSG-HELP 1
+.Os
+.Sh NAME
+.Nm ssg-help
+.Nd open the manual page for a command
+.Sh SYNOPSIS
+.Nm ssg help
+.Op Fl h | -help
+.Ar [<command>]
+.Sh DESCRIPTION
+.Nm
+opens the manual page for a command.
+.Pp
If no command is specified, opens the main
-.BR ssg (1)
+.Xr ssg 1
page.
-.SH EXAMPLES
-Show main documentation:
-.PP
-.RS
-.nf
-$ ssg help
-.fi
-.RE
-.PP
-Show build command documentation:
-.PP
-.RS
-.nf
-$ ssg help build
-.fi
-.RE
-.SH SSG
-Part of the
-.BR ssg (1)
-suite.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl h , Fl -help
+Print brief usage information.
+.El
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and >0 if an error occurs.
+.Sh EXAMPLES
+Show the manual page for
+.Xr ssg 1 :
+.Pp
+.Dl $ ssg help
+.Pp
+Show the manual page for
+.Xr ssg-build 1 :
+.Pp
+.Dl $ ssg help build
+.Sh SEE ALSO
+.Xr ssg 1
diff --git a/man/ssg-init.1 b/man/ssg-init.1
index 47dd2bb..909801b 100644
--- a/man/ssg-init.1
+++ b/man/ssg-init.1
@@ -1,45 +1,55 @@
-.TH SSG-INIT 1 "2026-01-01" "ssg" "General Commands Manual"
-.SH NAME
-ssg-init \- initialize a new site
-.SH SYNOPSIS
-.B ssg init
-.RI [ directory ]
-.SH DESCRIPTION
-Create a new site with the standard directory structure:
-.PP
-.RS
-.nf
-data/
-templates/
-static/
-.fi
-.RE
-.PP
-If no directory is specified, initializes in the current directory.
-A sample
-.I templates/index.html
-is created if one does not exist.
-.SH EXAMPLES
-Initialize in the current directory:
-.PP
-.RS
-.nf
-$ ssg init
-.fi
-.RE
-.PP
-Initialize a new site:
-.PP
-.RS
-.nf
-$ ssg init mysite
-$ cd mysite
-$ ssg build
-.fi
-.RE
-.SH SEE ALSO
-.BR ssg-build (1)
-.SH SSG
-Part of the
-.BR ssg (1)
-suite.
+.Dd January 2, 2026
+.Dt SSG-INIT 1
+.Os
+.Sh NAME
+.Nm ssg-init
+.Nd initialize a new site
+.Sh SYNOPSIS
+.Nm ssg init
+.Op Fl h | -help
+.Ar [directory]
+.Sh DESCRIPTION
+.Nm
+creates a new site with the standard directory structure:
+.Pp
+.Bl -item -offset indent -compact
+.It
+.Pa data/
+.It
+.Pa templates/index.html
+.It
+.Pa static/
+.El
+.Pp
+If no
+.Ar directory
+is specified, initializes in the current directory. A sample
+.Qq hello world
+.Pa templates/index.html
+is created if the file does not already exist.
+.Pp
+.Ar directory
+can be any relative path from the current working directory or any absolute path. If any subdirectories are missing along the given path, they will be created with 755 permissions.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl h , Fl -help
+Print brief usage information.
+.El
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and >0 if an error occurs.
+.Sh EXAMPLES
+Initialize a site in the current directory:
+.Dl $ ssg init
+.Pp
+Initialize, build, and serve a new site in a subdirectory:
+.Dl $ ssg init mysite
+.Dl $ cd mysite
+.Dl $ ssg build
+.Dl $ ssg serve
+.Pp
+.Sh SEE ALSO
+.Xr ssg 1 ,
+.Xr ssg-build 1 ,
+.Xr ssg-serve 1 ,
+.Xr ssg-templates 5
diff --git a/man/ssg-serve.1 b/man/ssg-serve.1
index ede5977..5d1ffd5 100644
--- a/man/ssg-serve.1
+++ b/man/ssg-serve.1
@@ -1,45 +1,50 @@
-.TH SSG-SERVE 1 "2026-01-01" "ssg" "General Commands Manual"
-.SH NAME
-ssg-serve \- serve the site locally
-.SH SYNOPSIS
-.B ssg serve
-.RI [ options ]
-.SH DESCRIPTION
-Start a local HTTP server to preview the built site.
-.SH OPTIONS
-.TP
-.BI \-dir " dir"
-Directory to serve. Default: dist
-.TP
-.BI \-addr " address"
-Address to listen on. Default: :8080
-.SH EXAMPLES
-Serve the default output directory:
-.PP
-.RS
-.nf
-$ ssg serve
-.fi
-.RE
-.PP
+.Dd January 2, 2026
+.Dt SSG-SERVE 1
+.Os
+.Sh NAME
+.Nm ssg-serve
+.Nd serve the built static site locally
+.Sh SYNOPSIS
+.Nm ssg serve
+.Op Fl h | -help
+.Op Fl d | -dir Ar dir
+.Op Fl p | -port Ar port
+.Sh DESCRIPTION
+.Nm
+starts a local HTTP server at
+.Lk http://localhost:8080
+to preview the built site.
+.Pp
+It is assumed that you have run
+.Xr ssg-build 1
+first. If not, the output directory may not exist and while the HTTP
+server will start up, any request to the server will result in a 404
+Not Found.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl h , Fl -help
+Print brief usage information.
+.It Fl d Ar dir , Fl -dir Ar dir
+Relative path to a directory to serve. Default: dist
+.It Fl p Ar port , Fl -port Ar port
+Port to listen on. Default: 8080
+.El
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and >0 if an error occurs.
+.Sh EXAMPLES
+Serve the default output directory on the default port:
+.Dl $ ssg serve
+.Pp
Serve on a different port:
-.PP
-.RS
-.nf
-$ ssg serve -addr=:3000
-.fi
-.RE
-.PP
+.Dl $ ssg serve --port 9000
+.Pp
+Serve on a different output directory:
+.Dl $ ssg serve --dir build/
+.Pp
Build and serve:
-.PP
-.RS
-.nf
-$ ssg build && ssg serve
-.fi
-.RE
-.SH SEE ALSO
-.BR ssg-build (1)
-.SH SSG
-Part of the
-.BR ssg (1)
-suite.
+.Dl $ ssg build && ssg serve
+.Pp
+.Sh SEE ALSO
+.Xr ssg 1 ,
+.Xr ssg-build 1
diff --git a/man/ssg-templates.5 b/man/ssg-templates.5
index 8f31920..156eef9 100644
--- a/man/ssg-templates.5
+++ b/man/ssg-templates.5
@@ -1,83 +1,86 @@
-.TH SSG-TEMPLATES 5 "2026-01-01" "ssg" "File Formats Manual"
-.SH NAME
-ssg-templates \- ssg template format
-.SH DESCRIPTION
-ssg templates use Go's
-.B html/template
-syntax. Each HTML file in the templates directory is processed and rendered
-to the output directory with the same filename.
-.SH DATA
-Data from JSON files in the data directory is made available to templates.
-Each file becomes a template variable named after the file (without the
-.I .json
+.Dd January 2, 2026
+.Dt SSG-TEMPLATES 5
+.Os
+.Sh NAME
+.Nm ssg-templates
+.Nd ssg template format
+.Sh DESCRIPTION
+Templates use Go's
+.Lk https://pkg.go.dev/html/template html/template
+syntax. Each HTML file in the templates directory (default:
+.Pa templates/ )
+is processed and rendered to
+the output directory with the same filename and directory structure.
+.Sh DATA
+Data from JSON files in the data directory (default:
+.Pa data/ )
+is made available to templates. Each file becomes a template variable named
+after the file (without the
+.Pa .json
extension).
-.PP
+.Pp
For example, if
-.I data/projects.json
+.Pa data/projects.json
contains:
-.PP
-.RS
-.nf
+.Bd -literal -offset indent
[
{"name": "foo", "url": "https://example.com/foo", "featured": true},
{"name": "bar", "url": "https://example.com/bar", "featured": false}
]
-.fi
-.RE
-.PP
+.Ed
+.Pp
It can be accessed in templates as
-.BR .projects :
-.PP
-.RS
-.nf
+.Va .projects :
+.Bd -literal -offset indent
{{range .projects}}
<li><a href="{{.url}}">{{.name}}</a></li>
{{end}}
-.fi
-.RE
-.SH FUNCTIONS
-.SS filter
-The
-.B filter
-function returns items from an array where a field equals a value.
-.PP
-.RS
-.nf
-{{range filter .projects "featured" true}}
- <li>{{.name}}</li>
-{{end}}
-.fi
-.RE
-.PP
-This would output only "foo" since it has
-.B featured
-set to
-.BR true .
-.SH SYNTAX
+.Ed
+.Sh SYNTAX
Templates use Go's text/template syntax:
-.TP
-.B {{.field}}
+.Bl -tag -width Ds
+.It Li {{.field}}
Output a field value.
-.TP
-.B {{range .items}}...{{end}}
+.It Li {{range .items}}...{{end}}
Iterate over a list.
-.TP
-.B {{if .condition}}...{{end}}
+.It Li {{if .condition}}...{{end}}
Conditional rendering.
-.TP
-.B {{with .object}}...{{end}}
+.It Li {{with .object}}...{{end}}
Set dot to the object for the block.
-.PP
+.El
+.Pp
See the Go
-.B html/template
+.Lk https://pkg.go.dev/html/template html/template
documentation for full syntax details.
-.SH FILES
-.TP
-.I data/*.json
-JSON data files. Each becomes a template variable.
-.TP
-.I templates/*.html
+.Sh FUNCTIONS
+In addition to Go's built-in template functions, the following
+functions are available.
+.Pp
+All examples use data from
+.Sx DATA .
+.Ss filter
+.Bd -literal
+filter <array> <field> <value>
+.Ed
+.Pp
+Returns items from an array where a field equals a value.
+.Bd -literal -offset indent
+{{range filter .projects "featured" true}}
+ <li>{{.name}}</li>
+{{end}}
+.Ed
+.Pp
+This would output only "foo" since it has
+.Va featured
+set to
+.Li true .
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa templates/*.html
HTML templates to render.
-.SH SEE ALSO
-.BR ssg (1),
-.BR ssg-build (1)
+.It Pa data/*.json
+JSON data files. Each becomes a template variable.
+.El
+.Sh SEE ALSO
+.Xr ssg 1 ,
+.Xr ssg-build 1
diff --git a/man/ssg-version.1 b/man/ssg-version.1
index b5d4902..ff8e3f3 100644
--- a/man/ssg-version.1
+++ b/man/ssg-version.1
@@ -1,11 +1,23 @@
-.TH SSG-VERSION 1 "2026-01-01" "ssg" "General Commands Manual"
-.SH NAME
-ssg-version \- print version
-.SH SYNOPSIS
-.B ssg version
-.SH DESCRIPTION
-Print the ssg version and exit.
-.SH SSG
-Part of the
-.BR ssg (1)
-suite.
+.Dd January 2, 2026
+.Dt SSG-VERSION 1
+.Os
+.Sh NAME
+.Nm ssg-version
+.Nd print version
+.Sh SYNOPSIS
+.Nm ssg version
+.Op Fl h | -help
+.Sh DESCRIPTION
+.Nm
+prints the version of
+.Xr ssg 1 .
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl h , Fl -help
+Print brief usage information.
+.El
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and >0 if an error occurs.
+.Sh SEE ALSO
+.Xr ssg 1
diff --git a/man/ssg.1 b/man/ssg.1
index 837fbf7..57666bd 100644
--- a/man/ssg.1
+++ b/man/ssg.1
@@ -1,50 +1,60 @@
-.TH SSG 1 "2026-01-01" "ssg" "General Commands Manual"
-.SH NAME
-ssg \- a tiny static site generator
-.SH SYNOPSIS
-.B ssg
-.I command
-.RI [ options ]
-.SH DESCRIPTION
-.B ssg
-is a minimal static site generator that reads JSON data files and renders
-Go templates to produce static HTML. Static assets are copied unchanged
-to the output directory.
-.SH COMMANDS
-.TP
-.BR ssg-build (1)
+.Dd January 2, 2026
+.Dt SSG 1
+.Os
+.Sh NAME
+.Nm ssg
+.Nd a tiny static site generator
+.Sh SYNOPSIS
+.Nm ssg
+.Op Fl h | -help
+.Ar <command>
+.Ar [<args>]
+.Sh DESCRIPTION
+.Nm
+is a tiny static site generator that can render Go templates to produce static
+HTML. If any JSON data files are provided, they are automatically accessible
+within the Go templates. Static assets are copied verbatim to the build output
+directory.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl h , Fl -help
+Print brief usage information.
+.El
+.Sh COMMANDS
+.Bl -tag -width Ds
+.It Xr ssg-build 1
Build the site.
-.TP
-.BR ssg-serve (1)
-Start a local HTTP server.
-.TP
-.BR ssg-init (1)
+.It Xr ssg-help 1
+Show the manual for a command.
+.It Xr ssg-init 1
Initialize a new site.
-.TP
-.BR ssg-version (1)
+.It Xr ssg-serve 1
+Start a local HTTP server serving the output directory.
+.It Xr ssg-version 1
Print the version.
-.TP
-.BR ssg-help (1)
-Show help for a command.
-.SH FILES
-.TP
-.I data/
-JSON data files. Each file becomes a template variable.
-.TP
-.I templates/
-HTML template files.
-.TP
-.I static/
-Static files copied unchanged.
-.TP
-.I dist/
-Default output directory.
-.SH SEE ALSO
-.BR ssg-build (1),
-.BR ssg-serve (1),
-.BR ssg-init (1),
-.BR ssg-version (1),
-.BR ssg-help (1),
-.BR ssg-templates (5)
-.SH AUTHOR
-Eugene Triguba <hello@eugenetriguba.com>
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa data/
+Data files to make available to the HTML templates.
+.It Pa templates/
+HTML template files using the Go templating language. See
+.Xr ssg-templates 5
+for details.
+.It Pa static/
+Any files that should be copied to the output directory when the site is built
+e.g. CSS, images, etc.
+.It Pa dist/
+Default output directory that contains the static files verbatim and the
+rendered HTML files. See
+.Xr ssg-build 1
+for details.
+.El
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and >0 if an error occurs.
+.Sh AUTHOR
+.Nm
+was written and is maintained by
+.An Eugene Triguba ,
+.Mt hello@eugenetriguba.com .