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
+5-12
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,7 @@
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].
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.
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.
10
8
11
9
== Repository structure
12
10
@@ -27,23 +25,18 @@ $ npm ci
27
25
$ make
28
26
----
29
27
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.
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.
33
29
34
30
== Production deployment
35
31
36
32
The documentation is deployed by Netlify on a regular basis or when something is pushed to the `main` branch.
37
33
To trigger an out of band deployment, use the _Build and deploy production site_ GitHub action (internal contributors only).
38
34
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.
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.
41
36
42
37
=== Netlify configuration
43
38
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`].
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`].
47
40
48
41
The build process creates a static site in `build/site` which is then published (as it is configured in the `netlify.toml`).
49
42
@@ -65,7 +58,7 @@ NOTE: Antora does not recognize git submodules as git repositories
65
58
66
59
The design & layout comes from our https://github.com/stackabletech/documentation-ui[UI repository].
67
60
68
-
`LIVERELOAD=true gulp` may be used to recreate the built documentation after each edit.
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
Copy file name to clipboardExpand all lines: modules/contributor/pages/docs/overview.adoc
+1-4
Original file line number
Diff line number
Diff line change
@@ -43,16 +43,13 @@ 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, Pagefind
46
+
== Technical bits: Antora, Netlify
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
-
56
53
For Antora, the https://antora.zulipchat.com/[Antora Zulip chatroom] is a good place to get help (besides the documentation)!
57
54
58
55
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