Skip to content

Commit f44696b

Browse files
fhennigFelix Henniglfrancke
authored
Update README to be more in line with our version of the UI (#30)
Co-authored-by: Felix Hennig <felix.hennig@stackable.tech> Co-authored-by: Lars Francke <git@lars-francke.de>
1 parent 5c08d9f commit f44696b

File tree

1 file changed

+51
-165
lines changed

1 file changed

+51
-165
lines changed

‎README.adoc‎

Lines changed: 51 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -3,214 +3,100 @@
33
:experimental:
44
:hide-uri-scheme:
55
// Project URLs:
6-
:url-project: https://gitlab.com/antora/antora-ui-default
6+
:url-default-ui: https://gitlab.com/antora/antora-ui-default
77
// External URLs:
88
:url-stackable-docs: https://docs.stackable.tech/
99
:url-antora-docs: https://docs.antora.org
1010
:url-git: https://git-scm.com
1111
:url-git-dl: {url-git}/downloads
12-
:url-gulp: http://gulpjs.com
1312
:url-opendevise: https://opendevise.com
1413
:url-nodejs: https://nodejs.org
1514
:url-nvm: https://github.com/creationix/nvm
1615
:url-nvm-install: {url-nvm}#installation
1716
:url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
1817

19-
This project is the UI template used on {url-stackable-docs}[the Stackable docs]. It is based on the Antora default UI. As intended, this repository is forked from the default UI and customized to our needs.
18+
This project is the UI template used on {url-stackable-docs}[the Stackable docs].
19+
It is based on (forked from) the {url-default-ui}[Antora default UI] and customized to our needs.
20+
The document below contains information about this repo, but consult the default UI README as well for additional useful information.
2021

21-
== Notes on our Customized Version
22-
23-
=== Tracking
24-
We have added our own tracking solution into `src/partials/head-scripts.hbs`. It has the URL hardcoded. it can be enabled by setting `site.keys.enable_tracking` to `true`/`false` in the Antora playbook.
25-
26-
=== Highlight.js v10
27-
[Ticket](https://github.com/stackabletech/documentation/issues/232) - Due to the removal of HTML-passthru in v11 (which we need for [Callouts](https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/)) the highlight.js has not been updated from v10. This also affects the Antora Default UI. Both decisions will be revisited when the upstream upgrade is available.
28-
29-
=== Search with pagefind
30-
We use https://pagefind.app/[pagefind] for search.
31-
The index is generated as part of the build in the `documentation` repository.
32-
Various `pagefind-*` tags are used to mark content that should be indexed.
33-
Only the stable docs are indexed (no previous versions, no nightly).
34-
35-
== Code of Conduct
36-
37-
The Antora project and its project spaces are governed by our https://gitlab.com/antora/antora/-/blob/HEAD/CODE-OF-CONDUCT.adoc[Code of Conduct].
38-
By participating, you're agreeing to honor this code.
39-
Let's work together to make this a welcoming, professional, inclusive, and safe environment for everyone.
40-
41-
== Use the Default UI
42-
43-
If you want to simply use the default UI for your Antora-generated site, add the following UI configuration to your playbook:
44-
45-
[source,yaml]
46-
----
47-
ui:
48-
bundle:
49-
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
50-
snapshot: true
51-
----
52-
53-
NOTE: The `snapshot` flag tells Antora to fetch the UI when the `--fetch` command-line flag is present.
54-
This setting is required because updates to the UI bundle are pushed to the same URL.
55-
If the URL were to be unique, this setting would not be required.
56-
57-
Read on to learn how to customize the default UI for your own documentation.
58-
59-
== Development Quickstart
60-
61-
This section offers a basic tutorial to teach you how to set up the default UI project, preview it locally, and bundle it for use with Antora.
62-
A more comprehensive tutorial can be found in the documentation at {url-antora-docs}.
22+
== Quickstart
6323

6424
=== Prerequisites
6525

6626
To preview and bundle the default UI, you need the following software on your computer:
6727

6828
* {url-git}[git] (command: `git`)
6929
* {url-nodejs}[Node.js] (commands: `node` and `npm`)
70-
* {url-gulp}[Gulp CLI] (command: `gulp`)
71-
72-
==== git
73-
74-
First, make sure you have git installed.
75-
76-
$ git --version
77-
78-
If not, {url-git-dl}[download and install] the git package for your system.
79-
80-
==== Node.js
81-
82-
Next, make sure that you have Node.js installed (which also provides npm).
83-
84-
$ node --version
85-
86-
If this command fails with an error, you don't have Node.js installed.
87-
If the command doesn't report an LTS version of Node.js (e.g., v10.15.3), it means you don't have a suitable version of Node.js installed.
88-
In this guide, we'll be installing Node.js 10.
89-
90-
While you can install Node.js from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to manage your Node.js installation(s).
91-
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.
92-
93-
Once you've installed nvm, open a new terminal and install Node.js 10 using the following command:
94-
95-
$ nvm install 10
96-
97-
You can switch to this version of Node.js at any time using the following command:
9830

99-
$ nvm use 10
31+
== Build process
10032

101-
To make Node.js 10 the default in new terminals, type:
33+
The UI is built with Gulp.
34+
Linting, bundling, and previewing are supported.
35+
This repository is referenced as a submodule in the documentation repository, and the bundling takes place there.
10236

103-
$ nvm alias default 10
37+
To create a bundle run:
38+
[source,js]
39+
npm ci
40+
npm run bundle
10441

105-
Now that you have Node.js installed, you can proceed with installing the Gulp CLI.
42+
It will be created in `build/ui-bundle.zip`
10643

107-
==== Gulp CLI
44+
== Project structure
10845

109-
You'll need the Gulp command-line interface (CLI) to run the build.
110-
The Gulp CLI package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project.
46+
The UI bundle is basically a collection of handlebars templates and some minimal JS and CSS, which is then filled with life with the documentation content. All of this lives in the `src` directory.
11147

112-
You can install the Gulp CLI globally (which resolves to a location in your user directory if you're using nvm) using the following command:
48+
Inside the `src` directory are:
11349

114-
$ npm install -g gulp-cli
50+
* `css`: Contains all the CSS. `site.css` contains imports of all the other files. In `vendor` there is the copied-in FontAwesome CSS file.
51+
* `helpers`: Contains Handlebars helper functions. The file names are the names of the helpers. You can use these inside the Handlebars templates.
52+
* `img`: Images used in the UI.
53+
* `js`: Contains JavaScript files for UI functionality, numbered for loading order. The `vendor` directory contains third-party libraries like highlight.js and tabs functionality.
54+
* `layouts`: Contains the main Handlebars layout templates. `default.hbs` is the standard page layout, `landing.hbs` is for landing pages with special styling, and `404.hbs` handles error pages. These templates define the overall page structure and include partials for header, body, and footer.
55+
* `partials`: Contains all the Handlebars files. This is the directory containing all the templated HTML for the site.
11556

116-
Verify the Gulp CLI is installed and on your PATH by running:
57+
=== Gulp
11758

118-
$ gulp --version
59+
To work on the build process of this, you need to understand https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles[gulp].
60+
Gulp is a builder/bundler that is used to package this antora UI.
11961

120-
If you prefer to install global packages using Yarn, run this command instead:
62+
In this project, `gulpfile.js` is the main entrypoint for gulp.
63+
This file references tasks in the `gulp.d` directory.
12164

122-
$ yarn global add gulp-cli
65+
You don't need to install the `gulp` CLI yourself, you can call package scripts (i.e. `npm run bundle` which will then call `gulp` from the `node_modules`).
12366

124-
Alternately, you can use the `gulp` command that is installed by the project's dependencies.
67+
=== Building the final documentation
12568

126-
$ $(npm bin)/gulp --version
69+
The documentation repository uses this repository as a submodule, bundles the UI on demand and then links to it like this in the Playbook:
12770

128-
Now that you have the prerequisites installed, you can fetch and build the UI project.
129-
130-
=== Clone and Initialize the UI Project
131-
132-
Clone the default UI project using git:
133-
134-
[subs=attributes+]
135-
$ git clone {url-project} &&
136-
cd "`basename $_`"
137-
138-
The example above clones Antora's default UI project and then switches to the project folder on your filesystem.
139-
Stay in this project folder when executing all subsequent commands.
140-
141-
Use npm to install the project's dependencies inside the project.
142-
In your terminal, execute the following command:
143-
144-
$ npm install
145-
146-
This command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.
147-
This folder does not get included in the UI bundle and should _not_ be committed to the source control repository.
148-
149-
[TIP]
150-
====
151-
If you prefer to install packages using Yarn, run this command instead:
152-
153-
$ yarn
154-
====
155-
156-
=== Preview the UI
157-
158-
The default UI project is configured to preview offline.
159-
The files in the [.path]_preview-src/_ folder provide the sample content that allow you to see the UI in action.
160-
In this folder, you'll primarily find pages written in AsciiDoc.
161-
These pages provide a representative sample and kitchen sink of content from the real site.
162-
163-
To build the UI and preview it in a local web server, run the `preview` command:
164-
165-
$ gulp preview
166-
167-
You'll see a URL listed in the output of this command:
168-
169-
....
170-
[12:00:00] Starting server...
171-
[12:00:00] Server started http://localhost:5252
172-
[12:00:00] Running server
173-
....
174-
175-
Navigate to this URL to preview the site locally.
71+
[source,yaml]
72+
ui:
73+
bundle:
74+
url: ./ui/build/ui-bundle.zip
17675

177-
While this command is running, any changes you make to the source files will be instantly reflected in the browser.
178-
This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
76+
=== Previewing the UI during development
17977

78+
It is useful to be able to see changes quickly while working on the UI.
79+
To start the preview at http://localhost:5252, run `npm run preview`.
18080
Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
18181

182-
=== Package for Use with Antora
82+
==== How it works
18383

184-
If you need to package the UI so you can use it to generate the documentation site locally, run the following command:
84+
The `preview-src` directory contains dummy docs content, which will be used to render the UI templates.
85+
The `ui-model.yml` contains dummy information similar to the antora-playbook.yaml.
18586

186-
$ gulp bundle
187-
188-
If any errors are reported by lint, you'll need to fix them.
189-
190-
When the command completes successfully, the UI bundle will be available at [.path]_build/ui-bundle.zip_.
191-
You can point Antora at this bundle using the `--ui-bundle-url` command-line option.
192-
193-
If you have the preview running, and you want to bundle without causing the preview to be clobbered, use:
194-
195-
$ gulp bundle:pack
196-
197-
The UI bundle will again be available at [.path]_build/ui-bundle.zip_.
198-
199-
==== Source Maps
200-
201-
The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle.
202-
{url-source-maps}[Source maps] correlate these combined files with their original sources.
203-
204-
This "`source mapping`" is accomplished by generating additional map files that make this association.
205-
These map files sit adjacent to the combined files in the build folder.
206-
The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging.
87+
== Notes on our Customized Version
20788

208-
In preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them.
209-
If you need to include source maps in the bundle, you can do so by setting the `SOURCEMAPS` environment variable to `true` when you run the bundle command:
89+
=== Tracking
90+
We have added our own tracking solution into `src/partials/head-scripts.hbs`. It has the URL hardcoded. it can be enabled by setting `site.keys.enable_tracking` to `true`/`false` in the Antora playbook.
21091

211-
$ SOURCEMAPS=true gulp bundle
92+
=== Highlight.js v10
93+
[Ticket](https://github.com/stackabletech/documentation/issues/232) - Due to the removal of HTML-passthru in v11 (which we need for [Callouts](https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/)) the highlight.js has not been updated from v10. This also affects the Antora Default UI. Both decisions will be revisited when the upstream upgrade is available.
21294

213-
In this case, the bundle will include the source maps, which can be used for debugging your production site.
95+
=== Search with pagefind
96+
We use https://pagefind.app/[pagefind] for search.
97+
The index is generated as part of the build in the `documentation` repository.
98+
Various `pagefind-*` tags are used to mark content that should be indexed.
99+
Only the stable docs are indexed (no previous versions, no nightly).
214100

215101
== Copyright and License
216102

0 commit comments

Comments
 (0)