diff options
| -rw-r--r-- | README.adoc | 34 | ||||
| -rw-r--r-- | site-workspace.yml | 19 | ||||
| -rw-r--r-- | site.yml | 13 |
3 files changed, 66 insertions, 0 deletions
diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..80e7d9f --- /dev/null +++ b/README.adoc @@ -0,0 +1,34 @@ += Alpine Documentation +Chloe Kudryavtsev <toast@toastin.space> + +This is the Antora playbook for the Alpine Documentation. + +== Deploying + +This repository is all you need to deploy the documentation. +You should clone this, and then run `antora generate [ARGS] playbook.yml`, where "playbook.yml" is the appropriate playbook. +Here are the available playbooks: + +site.yml:: Production playbook - use this if you're deploying this externally. +site-workspace.yml:: +Author mode playbook - use this if you're working on the documentation. +This expects checkouts (or symlinks) to the components to be under `workspace/`. +It will also generate a `./public.zip`, which is how the snapshots are created. + +Args of particular interest are: + +`--cache-dir`:: Puts the cache into a specified directory - since the default is under home, you may want to set this to, for example, `build/cache`. +`--clean`:: Cleans up the target directory before building. +`--pull`:: Force checking for upstream updates (components, ui, etc). +`--to-dir`:: Determines where the results are put - defaults to `build/site`, you may want to use `public`. +`--url`:: Sets the base url, which allows generating 404 and similar directories - do not add a trailing `/` - example: `https://docs.alpinelinux.org`. + +Thus, a production deployment to https://docs.alpinelinux.org would look like so: `antora --cache-dir build/cache --clean --url https://docs.alpinelinux.org site.yml`, and the web server would be pointed at `$PWD/build/site`. + +== Contributing + +There are few reasons to contribute to here - this is just the glue between actual content. +You are likely interested in contributing to one of the Antora components, referenced here. +In the scenario there is something specific to contribute anyway, please make sure your name is in the authors list. +Do also note that by contributing a patch, assuming you have not done so yet, you are agreeing to license your patch (and all future ones) under the license of the repository. +You will be explicitly asked to confirm that in whatever medium you submit that patch (or you may confirm this in your patch commit message). diff --git a/site-workspace.yml b/site-workspace.yml new file mode 100644 index 0000000..c20b6cd --- /dev/null +++ b/site-workspace.yml @@ -0,0 +1,19 @@ +site: + title: Alpine Linux Documentation + start_page: user-handbook::index.adoc + +content: + sources: + - url: workspace/user-handbook + branches: HEAD + +ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true + +output: + destinations: + - provider: archive + path: ./public.zip + - provider: fs diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..9809695 --- /dev/null +++ b/site.yml @@ -0,0 +1,13 @@ +site: + title: Alpine Linux Documentation + start_page: user-handbook::index.adoc + +content: + sources: + - url: https://github.com/5paceToast/alpine-user-handbook.git + branches: [ master ] + +ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true |