Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,8 @@ build-prod: build-ui
build-ui:
node_modules/.bin/gulp --cwd ui bundle

# build the search index and add pagefind files to the output.
build-search-index:
npm run build-search-index
npx pagefind --site build/site

serve:
python3 -m http.server -d build/site
Expand Down
17 changes: 5 additions & 12 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,7 @@
This is the main repository for the documentation of the Stackable platform.
Have a look at the https://docs.stackable.tech/[live version] and the current https://docs.stackable.tech/home/nightly/[nightly live version].

The documentation is built with https://antora.org[Antora].
This repository hosts the Antora playbook file as well as platform documentation.
Other Stackable repos contain 'docs' directories which are pulled in by this repo.
The documentation is built with https://antora.org[Antora]. This repository hosts the Antora playbook file as well as platform documentation. Other Stackable repos contain 'docs' directories which are pulled in by this repo.

== Repository structure

Expand All @@ -27,23 +25,18 @@ $ npm ci
$ make
----

NOTE: Antora caches the external content repos in the cache directory (configured to be `./cache`)
It will _not_ automatically update those.
Use the `--fetch` flag (`make ANTORAFLAGS=--fetch`) to update all sources, or use `make clean` to delete the `cache` and `build` directory.
NOTE: Antora caches the external content repos in the cache directory (configured to be `./cache`). It will _not_ automatically update those. Use the `--fetch` flag (`make ANTORAFLAGS=--fetch`) to update all sources, or use `make clean` to delete the `cache` and `build` directory.

== Production deployment

The documentation is deployed by Netlify on a regular basis or when something is pushed to the `main` branch.
To trigger an out of band deployment, use the _Build and deploy production site_ GitHub action (internal contributors only).

Regular (nightly) deployments are run to pick up changes in the operator repositories.
These repositories are not watched by Netlify and thus any changes to the documentation there would be ignored.
Regular (nightly) deployments are run to pick up changes in the operator repositories. These repositories are not watched by Netlify and thus any changes to the documentation there would be ignored.

=== Netlify configuration

Netlify is configured with the link:netlify.toml[`netlify.toml`] file inside of the documentation repo.
In there, the command `make netlify-build` is configured as the build command.
Further documentation of the build process can then be found in the link:Makefile[`Makefile`].
Netlify is configured with the link:netlify.toml[`netlify.toml`] file inside of the documentation repo. In there, the command `make netlify-build` is configured as the build command. Further documentation of the build process can then be found in the link:Makefile[`Makefile`].

The build process creates a static site in `build/site` which is then published (as it is configured in the `netlify.toml`).

Expand All @@ -65,7 +58,7 @@ NOTE: Antora does not recognize git submodules as git repositories

The design & layout comes from our https://github.com/stackabletech/documentation-ui[UI repository].

`LIVERELOAD=true gulp` may be used to recreate the built documentation after each edit.
`LIVERELOAD=true gulp` may be used to recreate the built documentation after each edit. The 'live reload' feature does not work over gitpod currently due to https://github.com/schickling/gulp-webserver/pull/126

== More useful links

Expand Down
5 changes: 1 addition & 4 deletions modules/contributor/pages/docs/overview.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -43,16 +43,13 @@ The reference is found at https://crds.stackable.tech/ and generated from the ht

The xref:docs/style-guide.adoc[] contains all the information about the writing style, formatting style, naming documents and more.

== Technical bits: Antora, Netlify, Pagefind
== Technical bits: Antora, Netlify

{antora-docs}[Antora] uses a {antora-playbook}[playbook] to build the documentation.
It pulls information from all the individual operators, so their documentation can live in the same repository.
Antora builds a static website which we serve over {netlify}[Netlify].
The web template of the documentation is also custom made and is developed in the https://github.com/stackabletech/documentation-ui[documentation-ui] repository.

For search, we use https://pagefind.app/[pagefind] - a static search.
The search index is generated as part of the build process and no external index is queried during search.

For Antora, the https://antora.zulipchat.com/[Antora Zulip chatroom] is a good place to get help (besides the documentation)!

Building the documentation and also the deployment process on Netlify are documented in the https://github.com/stackabletech/documentation/blob/main/README.adoc[README] file of the documentation repository.
Expand Down
85 changes: 2 additions & 83 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 2 additions & 6 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,17 +1,13 @@
{
"devDependencies": {
"@antora/cli": "^3.1.7",
"@antora/site-generator": "^3.1.7",
"pagefind": "^1.1.0"
"@antora/site-generator": "^3.1.7"
},
"dependencies": {
"@antora/lunr-extension": "^1.0.0-alpha.8",
"@asciidoctor/tabs": "^1.0.0-beta.6"
},
"workspaces": [
"ui"
],
"scripts": {
"build-search-index": "npx pagefind --site build/site"
}
]
}