You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.adoc
+12-5
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,9 @@
4
4
This is the main repository for the documentation of the Stackable platform.
5
5
Have a look at the https://docs.stackable.tech/[live version] and the current https://docs.stackable.tech/home/nightly/[nightly live version].
6
6
7
-
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.
7
+
The documentation is built with https://antora.org[Antora].
8
+
This repository hosts the Antora playbook file as well as platform documentation.
9
+
Other Stackable repos contain `docs` directories which are pulled in by this repo.
8
10
9
11
== Repository structure
10
12
@@ -25,18 +27,23 @@ $ npm ci
25
27
$ make
26
28
----
27
29
28
-
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.
30
+
NOTE: Antora caches the external content repos in the cache directory (configured to be `./cache`).
31
+
It will _not_ automatically update those.
32
+
Use the `--fetch` flag (`make ANTORAFLAGS=--fetch`) to update all sources, or use `make clean` to delete the `cache` and `build` directory.
29
33
30
34
== Production deployment
31
35
32
36
The documentation is deployed by Netlify on a regular basis or when something is pushed to the `main` branch.
33
37
To trigger an out of band deployment, use the _Build and deploy production site_ GitHub action (internal contributors only).
34
38
35
-
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.
39
+
Regular (nightly) deployments are run to pick up changes in the operator repositories.
40
+
These repositories are not watched by Netlify and thus any changes to the documentation there would be ignored.
36
41
37
42
=== Netlify configuration
38
43
39
-
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`].
44
+
Netlify is configured with the link:netlify.toml[`netlify.toml`] file inside of the documentation repo.
45
+
In there, the command `make netlify-build` is configured as the build command.
46
+
Further documentation of the build process can then be found in the link:Makefile[`Makefile`].
40
47
41
48
The build process creates a static site in `build/site` which is then published (as it is configured in the `netlify.toml`).
42
49
@@ -58,7 +65,7 @@ NOTE: Antora does not recognize git submodules as git repositories
58
65
59
66
The design & layout comes from our https://github.com/stackabletech/documentation-ui[UI repository].
60
67
61
-
`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
68
+
`LIVERELOAD=true gulp` may be used to recreate the built documentation after each edit.
Copy file name to clipboardExpand all lines: modules/contributor/pages/docs/overview.adoc
+4-1
Original file line number
Diff line number
Diff line change
@@ -43,13 +43,16 @@ The reference is found at https://crds.stackable.tech/ and generated from the ht
43
43
44
44
The xref:docs/style-guide.adoc[] contains all the information about the writing style, formatting style, naming documents and more.
45
45
46
-
== Technical bits: Antora, Netlify
46
+
== Technical bits: Antora, Netlify, Pagefind
47
47
48
48
{antora-docs}[Antora] uses a {antora-playbook}[playbook] to build the documentation.
49
49
It pulls information from all the individual operators, so their documentation can live in the same repository.
50
50
Antora builds a static website which we serve over {netlify}[Netlify].
51
51
The web template of the documentation is also custom made and is developed in the https://github.com/stackabletech/documentation-ui[documentation-ui] repository.
52
52
53
+
For search, we use https://pagefind.app/[pagefind] - a static search.
54
+
The search index is generated as part of the build process and no external index is queried during search.
55
+
53
56
For Antora, the https://antora.zulipchat.com/[Antora Zulip chatroom] is a good place to get help (besides the documentation)!
54
57
55
58
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.
0 commit comments