diff --git a/README.adoc b/README.adoc index c949591..1dc04cb 100644 --- a/README.adoc +++ b/README.adoc @@ -3,63 +3,23 @@ :experimental: :hide-uri-scheme: // Project URLs: -:url-project: https://gitlab.com/antora/antora-ui-default +:url-default-ui: https://gitlab.com/antora/antora-ui-default // External URLs: :url-stackable-docs: https://docs.stackable.tech/ :url-antora-docs: https://docs.antora.org :url-git: https://git-scm.com :url-git-dl: {url-git}/downloads -:url-gulp: http://gulpjs.com :url-opendevise: https://opendevise.com :url-nodejs: https://nodejs.org :url-nvm: https://github.com/creationix/nvm :url-nvm-install: {url-nvm}#installation :url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map -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. +This project is the UI template used on {url-stackable-docs}[the Stackable docs]. +It is based on (forked from) the {url-default-ui}[Antora default UI] and customized to our needs. +The document below contains information about this repo, but consult the default UI README as well for additional useful information. -== Notes on our Customized Version - -=== Tracking -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. - -=== Highlight.js v10 -[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. - -=== Search with pagefind -We use https://pagefind.app/[pagefind] for search. -The index is generated as part of the build in the `documentation` repository. -Various `pagefind-*` tags are used to mark content that should be indexed. -Only the stable docs are indexed (no previous versions, no nightly). - -== Code of Conduct - -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]. -By participating, you're agreeing to honor this code. -Let's work together to make this a welcoming, professional, inclusive, and safe environment for everyone. - -== Use the Default UI - -If you want to simply use the default UI for your Antora-generated site, add the following UI configuration to your playbook: - -[source,yaml] ----- -ui: - bundle: - url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable - snapshot: true ----- - -NOTE: The `snapshot` flag tells Antora to fetch the UI when the `--fetch` command-line flag is present. -This setting is required because updates to the UI bundle are pushed to the same URL. -If the URL were to be unique, this setting would not be required. - -Read on to learn how to customize the default UI for your own documentation. - -== Development Quickstart - -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. -A more comprehensive tutorial can be found in the documentation at {url-antora-docs}. +== Quickstart === Prerequisites @@ -67,150 +27,76 @@ To preview and bundle the default UI, you need the following software on your co * {url-git}[git] (command: `git`) * {url-nodejs}[Node.js] (commands: `node` and `npm`) -* {url-gulp}[Gulp CLI] (command: `gulp`) - -==== git - -First, make sure you have git installed. - - $ git --version - -If not, {url-git-dl}[download and install] the git package for your system. - -==== Node.js - -Next, make sure that you have Node.js installed (which also provides npm). - - $ node --version - -If this command fails with an error, you don't have Node.js installed. -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. -In this guide, we'll be installing Node.js 10. - -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). -Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine. - -Once you've installed nvm, open a new terminal and install Node.js 10 using the following command: - - $ nvm install 10 - -You can switch to this version of Node.js at any time using the following command: - $ nvm use 10 +== Build process -To make Node.js 10 the default in new terminals, type: +The UI is built with Gulp. +Linting, bundling, and previewing are supported. +This repository is referenced as a submodule in the documentation repository, and the bundling takes place there. - $ nvm alias default 10 +To create a bundle run: +[source,js] +npm ci +npm run bundle -Now that you have Node.js installed, you can proceed with installing the Gulp CLI. +It will be created in `build/ui-bundle.zip` -==== Gulp CLI +== Project structure -You'll need the Gulp command-line interface (CLI) to run the build. -The Gulp CLI package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project. +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. -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: +Inside the `src` directory are: - $ npm install -g gulp-cli +* `css`: Contains all the CSS. `site.css` contains imports of all the other files. In `vendor` there is the copied-in FontAwesome CSS file. +* `helpers`: Contains Handlebars helper functions. The file names are the names of the helpers. You can use these inside the Handlebars templates. +* `img`: Images used in the UI. +* `js`: Contains JavaScript files for UI functionality, numbered for loading order. The `vendor` directory contains third-party libraries like highlight.js and tabs functionality. +* `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. +* `partials`: Contains all the Handlebars files. This is the directory containing all the templated HTML for the site. -Verify the Gulp CLI is installed and on your PATH by running: +=== Gulp - $ gulp --version +To work on the build process of this, you need to understand https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles[gulp]. +Gulp is a builder/bundler that is used to package this antora UI. -If you prefer to install global packages using Yarn, run this command instead: +In this project, `gulpfile.js` is the main entrypoint for gulp. +This file references tasks in the `gulp.d` directory. - $ yarn global add gulp-cli +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`). -Alternately, you can use the `gulp` command that is installed by the project's dependencies. +=== Building the final documentation - $ $(npm bin)/gulp --version +The documentation repository uses this repository as a submodule, bundles the UI on demand and then links to it like this in the Playbook: -Now that you have the prerequisites installed, you can fetch and build the UI project. - -=== Clone and Initialize the UI Project - -Clone the default UI project using git: - -[subs=attributes+] - $ git clone {url-project} && - cd "`basename $_`" - -The example above clones Antora's default UI project and then switches to the project folder on your filesystem. -Stay in this project folder when executing all subsequent commands. - -Use npm to install the project's dependencies inside the project. -In your terminal, execute the following command: - - $ npm install - -This command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project. -This folder does not get included in the UI bundle and should _not_ be committed to the source control repository. - -[TIP] -==== -If you prefer to install packages using Yarn, run this command instead: - - $ yarn -==== - -=== Preview the UI - -The default UI project is configured to preview offline. -The files in the [.path]_preview-src/_ folder provide the sample content that allow you to see the UI in action. -In this folder, you'll primarily find pages written in AsciiDoc. -These pages provide a representative sample and kitchen sink of content from the real site. - -To build the UI and preview it in a local web server, run the `preview` command: - - $ gulp preview - -You'll see a URL listed in the output of this command: - -.... -[12:00:00] Starting server... -[12:00:00] Server started http://localhost:5252 -[12:00:00] Running server -.... - -Navigate to this URL to preview the site locally. +[source,yaml] +ui: + bundle: + url: ./ui/build/ui-bundle.zip -While this command is running, any changes you make to the source files will be instantly reflected in the browser. -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. +=== Previewing the UI during development +It is useful to be able to see changes quickly while working on the UI. +To start the preview at http://localhost:5252, run `npm run preview`. Press kbd:[Ctrl+C] to stop the preview server and end the continuous build. -=== Package for Use with Antora +==== How it works -If you need to package the UI so you can use it to generate the documentation site locally, run the following command: +The `preview-src` directory contains dummy docs content, which will be used to render the UI templates. +The `ui-model.yml` contains dummy information similar to the antora-playbook.yaml. - $ gulp bundle - -If any errors are reported by lint, you'll need to fix them. - -When the command completes successfully, the UI bundle will be available at [.path]_build/ui-bundle.zip_. -You can point Antora at this bundle using the `--ui-bundle-url` command-line option. - -If you have the preview running, and you want to bundle without causing the preview to be clobbered, use: - - $ gulp bundle:pack - -The UI bundle will again be available at [.path]_build/ui-bundle.zip_. - -==== Source Maps - -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. -{url-source-maps}[Source maps] correlate these combined files with their original sources. - -This "`source mapping`" is accomplished by generating additional map files that make this association. -These map files sit adjacent to the combined files in the build folder. -The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging. +== Notes on our Customized Version -In preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them. -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: +=== Tracking +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. - $ SOURCEMAPS=true gulp bundle +=== Highlight.js v10 +[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. -In this case, the bundle will include the source maps, which can be used for debugging your production site. +=== Search with pagefind +We use https://pagefind.app/[pagefind] for search. +The index is generated as part of the build in the `documentation` repository. +Various `pagefind-*` tags are used to mark content that should be indexed. +Only the stable docs are indexed (no previous versions, no nightly). == Copyright and License