{"id":20816352,"url":"https://github.com/riptano/antora-ui-docs","last_synced_at":"2026-04-22T00:32:56.205Z","repository":{"id":38886966,"uuid":"370778742","full_name":"riptano/antora-ui-docs","owner":"riptano","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-03T21:15:56.000Z","size":72466,"stargazers_count":1,"open_issues_count":15,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-12-28T16:21:58.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riptano.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-05-25T17:40:17.000Z","updated_at":"2023-03-16T17:05:58.000Z","dependencies_parsed_at":"2024-03-03T22:26:53.002Z","dependency_job_id":"bfecbae7-e8e2-44be-ad2b-c2a30b9d6891","html_url":"https://github.com/riptano/antora-ui-docs","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/riptano/antora-ui-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fantora-ui-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fantora-ui-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fantora-ui-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fantora-ui-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riptano","download_url":"https://codeload.github.com/riptano/antora-ui-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fantora-ui-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32115881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T00:31:26.853Z","status":"ssl_error","status_checked_at":"2026-04-22T00:30:22.894Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T21:29:56.483Z","updated_at":"2026-04-22T00:32:56.191Z","avatar_url":"https://github.com/riptano.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"= DataStax Antora UI\n// Variables:\n:current-release: prod-21\n// Settings:\n:!example-caption:\n:experimental:\n:hide-uri-scheme:\n:toc: macro\nifndef::env-github[]\n:icons: font\n:toc-title: Contents\nendif::[]\nifdef::env-github[]\n:important-caption: :exclamation:\n:note-caption: :paperclip:\n:!toc-title:\n:badges:\nendif::[]\n// Project URIs:\n:project-repo-name: riptano/antora-ui-docs\n:url-repo: git@github.com:{project-repo-name}.git\n:url-project: https://github.com/{project-repo-name}\n:url-site: https://docs.datastax.com\n:url-coppi: https://coppi.aws.dsinternal.org\n:url-docs-preview: http://docs-preview.datastax.com\n// External URIs:\n:url-antora: https://antora.org\n:url-git: https://git-scm.com\n:url-git-dl: {url-git}/downloads\n:url-gulp: http://gulpjs.com\n:url-node: https://nodejs.org\n:url-nvm: https://github.com/creationix/nvm\n:url-nvm-install: {url-nvm}#installation\n:url-datastax: https://datastax.com\n:url-docs-home: https://github.com/riptano/docs-home\n\nifdef::badges[]\nimage:https://img.shields.io/static/v1?label=release\u0026amp;message={current-release}\u0026amp;color=blue[Latest Release,link={url-project}/releases/download/{current-release}/ui-bundle.zip,format=svg]\nendif::[]\n\ntoc::[]\n\nThis project is used to develop and distribute the UI for the {url-site}[DataStax documentation site].\n\nThe UI bundle this project produces is intended to be used with {url-antora}[Antora].\nThe UI bundle contains the HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and _site-wide_ images.\nAs such, it provides both the visual theme and user interactions for the documentation site.\n\nThe base code for this project is supplied by the {url-antora-default-ui}[Antora Default UI], with DataStax-specific components templated over the top.\n\n[#usage]\n== Usage\n\nTo use this UI with Antora, add the following configuration to your playbook file:\n\n[source,yaml,subs=attributes+]\n----\nui:\n  bundle:\n    url: https://github.com/riptano/antora-ui-docs/releases/latest/download/ui-bundle.zip\n    snapshot: true\n----\n\nNOTE: The `snapshot` flag tells Antora to fetch the UI when the `--fetch` command-line flag is present.\nThis setting is required because updates to the UI bundle are pushed to the same URL.\nIf the URL were to be unique, this setting would not be required.\n\n[#search-dependencies]\n=== About site search UI dependencies\n\nAdditional tasks must be performed in order for the site search functionality on {url-site}[docs.datastax.com] to work properly.\nThese tasks only need to be performed when changes are made to the following files:\n\n[%header.autowidth.stretch]\n|===\n|Files |Tasks\n\n|{url-project}/blob/main/gcx/algoliaSearch/index.html[_gcx/algoliaSearch/index.html_]\n|Copy this file to the _/en/search_ directory on the {url-coppi}/en/search/[coppi] and {url-docs-preview}/en/search/[docs-preview] servers.\n\n|{url-project}/tree/main/gcx/algoliaSearch/src[_gcx/algoliaSearch/src/*_]\n|Copy these files to the _playbooks/supplemental-ui_ directory in the {url-docs-home}/tree/main/playbooks/supplemental-ui[docs-home] repository.\n|===\n\nIn the {url-docs-home}[docs-home] repository, the {url-docs-home}/blob/main/playbooks/site-local-home.yaml[_site-local-home.yaml_] and {url-docs-home}/blob/main/playbooks/site-publish-home.yaml[_site-publish-home.yaml_] playbooks are configured to incorporate the files from the _supplemental-ui_ directory into the assets directory of the generated site:\n\n[source,yaml]\n----\nui:\n  supplemental_files:\n  - path: css/siteSearch.css\n    contents: ./supplemental-ui/siteSearch.css\n  - path: js/siteSearch.js\n    contents: ./supplemental-ui/siteSearch.js\n  output_dir: assets\n----\n\nWhenever files are changed or added within the _supplemental-ui_ directory, the `home` docset must then be built and deployed to all of the docs servers to ensure that the servers have the latest site search assets.\n\n[source,console]\n----\nbsys build home\nbsys deploy home coppi\nbsys deploy home docs-preview\nbsys sync\n----\n\n.coppi asset locations\n----\n/var/www/en/home/assets/css/siteSearch.css\n/var/www/en/home/assets/js/siteSearch.js\n----\n\n.docs-preview asset locations\n----\n/datastax/www/docs.datastax.com/en/home/assets/css/siteSearch.css\n/datastax/www/docs.datastax.com/en/home/assets/js/siteSearch.js\n----\n\n== Development quickstart\n\nThis section offers a basic tutorial to teach you how to set up the UI project, preview it locally, and bundle it for use with Antora.\nA more comprehensive tutorial can be found in the documentation at {url-antora-docs}.\n\n[#dev-prerequisites]\n=== Prerequisites\n\nTo preview and bundle the UI, you need the following software on your computer:\n\n* {url-git}[git] (command: `git`)\n* {url-nodejs}[Node.js] (commands: `node` and `npm`)\n* {url-gulp}[Gulp CLI] (command: `gulp`)\n\n==== git\n\nFirst, make sure you have git installed.\n\n[source,shell]\n----\ngit --version\n----\n\nIf not, {url-git-dl}[download and install] the git package for your system.\n\n==== Node.js\n\nNext, make sure that you have Node.js installed (which also provides npm).\n\n[source,shell]\n----\nnode --version\n----\n\nIf this command fails with an error, you don't have Node.js installed.\nIf the command doesn't report an LTS version of Node.js (e.g., v16.17.1), it means you don't have a suitable version of Node.js installed.\nIn this guide, we'll be installing Node.js 16.\n\nWhile 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).\nFollow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.\n\nOnce you've installed nvm, open a new terminal and install Node.js 16 using the following command:\n\n[source,shell]\n----\nnvm install 16\n----\n\nYou can switch to this version of Node.js at any time using the following command:\n\n[source,shell]\n----\nnvm use 16\n----\n\nTo make Node.js 16 the default in new terminals, type:\n\n[source,shell]\n----\nnvm alias default 16\n----\n\nNow that you have Node.js installed, you can proceed with installing the Gulp CLI.\n\n==== Gulp CLI\n\nYou'll need the Gulp command-line interface (CLI) to run the build.\nThe Gulp CLI package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project.\n\nYou can install the Gulp CLI globally (which resolves to a location in your user directory if you're using nvm) using the following command:\n\n[source,shell]\n----\nnpm install -g gulp-cli\n----\n\nVerify the Gulp CLI is installed and on your PATH by running:\n\n[source,shell]\n----\ngulp --version\n----\n\nIf you prefer to install global packages using Yarn, run this command instead:\n\n[source,shell]\n----\nyarn global add gulp-cli\n----\n\nAlternately, you can use the `gulp` command that is installed by the project's dependencies.\n\n[source,shell]\n----\n$(npm bin)/gulp --version\n----\n\nNow that you have the prerequisites installed, you can fetch and build the UI project.\n\n=== Clone and initialize the UI project\n\nClone the UI project using git:\n\n[subs=attributes+]\n----\ngit clone {url-project} \u0026\u0026\n cd \"`basename $_`\"\n----\n\nThe example above clones the UI project and then switches to the project folder on your filesystem.\nStay in this project folder when executing all subsequent commands.\n\nIf you are testing UI bundle changes from a PR that is not yet merged to `main`, checkout the branch. Example:\n\n[source,shell]\n----\ngit checkout feature/new-helios-base\n----\n\nUse npm to install the project's dependencies inside the project.\nIn your terminal, execute the following command:\n\n[source,shell]\n----\nnpm install\n----\n\nThis command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.\nThis folder does not get included in the UI bundle and should _not_ be committed back to this repository.\n\n[TIP]\n====\nIf you prefer to install packages using Yarn, run this command instead:\n\n[source,shell]\n----\nyarn\n----\n====\n\n=== Preview the UI\n\nThis UI project is configured to preview offline.\nThe files in the [.path]_preview-src/_ folder provide the sample content that allow you to see the UI in action.\nIn this folder, you'll primarily find pages written in AsciiDoc.\nThese pages provide a representative sample and kitchen sink of content from the real site.\n\nIf you are testing UI bundle changes from a PR that is not yet merged to `main`, and if you haven't already, remember to checkout the branch. Example:\n\n[source,shell]\n----\ngit checkout feature/new-helios-base\n----\n\nRun the `npm install` command again.\n\n[source,shell]\n----\nnpm install\n----\n\nNow, to build the UI and preview it in a local web server, run the `preview` command:\n\n[source,shell]\n----\ngulp preview\n----\n\nYou'll see a URL listed in the output of this command:\n\n....\n[12:00:00] Starting server...\n[12:00:00] Server started http://localhost:5252\n[12:00:00] Running server\n....\n\nNavigate to this URL to preview the site locally.\n\nWhile this command is running, any changes you make to the source files will be instantly reflected in the browser.\nThis works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.\n\nPress kbd:[Ctrl+C] to stop the preview server and end the continuous build.\n\n[#package]\n=== Package for use with Antora\n\nIf you need to package the UI so you can use it to generate the documentation site locally, run the following command:\n\n[source,shell]\n----\ngulp bundle\n----\n\nIf any errors are reported by lint, you'll need to fix them.\n\nWhen the command completes successfully, the UI bundle will be available at [.path]_build/ui-bundle.zip_.\nYou can point Antora at this bundle using the `--ui-bundle-url` command-line option.\n\nIf you have the preview running, and you want to bundle without causing the preview to be clobbered, use:\n\n[source,shell]\n----\ngulp bundle:pack\n----\n\nThe UI bundle will again be available at [.path]_build/ui-bundle.zip_.\n\n=== Package for use with Antora adding Helios GCX\n\nTo include Helios GCX to the Antora bundle, you can build it following these steps:\n\nInstall the Node dependencies from the `./gcx` folder:\n\n[source,shell]\n----\ncd ./gcx\nnpm install\n----\n\nOnce it finished, you can run on this folder:\n\n[source,shell]\n----\nnpm run bundle\n----\n\nThis script will run both Antora and Helios bundlers, the final build you can find it on `./gcx/build` as `ui-bundle.zip`\n\n==== Source maps\n\nThe 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.\n{url-source-maps}[Source maps] correlate these combined files with their original sources.\n\nThis \"`source mapping`\" is accomplished by generating additional map files that make this association.\nThese map files sit adjacent to the combined files in the build folder.\nThe mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging.\n\nIn preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them.\nIf 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:\n\n[source,shell]\n----\nSOURCEMAPS=true gulp bundle\n----\n\nIn this case, the bundle will include the source maps, which can be used for debugging your production site.\n\n== Release the UI bundle\n\nOnce you're satisfied with the changes you've made to the UI and would like to make those changes available to Antora, you'll need to publish the UI as a bundle by making a release.\nThe bundle can then be downloaded from this repository using a unique URL.\nYou can see a list of all past releases on the {url-project}/releases[releases page].\n\nNOTE: All DataStax docs are configured to pull the latest, non-pre-release UI bundle.\nSee the \u003c\u003cusage\u003e\u003e section for an example of how this behavior is configured in a site playbook.\n\n=== Release task workflow\n\nIn addition to the \u003c\u003cdev-prerequisites\u003e\u003e covered above, you'll need to complete the following steps to release a new UI bundle:\n\n. Pack the UI bundle as described in \u003c\u003cpackage\u003e\u003e.\n+\n[source,shell]\n----\ngulp bundle\n----\n\n. Follow the GitHub instructions for {url-create-release}[creating a release].\n.. Create a new tag using the next version number in the sequence (e.g., prod-2 after prod-1)\n.. Make sure that the new tag targets the `main` branch.\n.. Title the release with the same name as the tag.\n(The release title and the tag name should always be the same, as it makes releases easier to identify.)\n.. (Optional) Add a description for the release that highlights the functional changes that have been added since the last release.\n.. Attach the UI bundle, located in [.path]_gcx/build/ui-bundle.zip_`, as a release asset.\n.. Check the box labeled *This is a pre-release* if you don't want the release to be generally available.\n+\nSelecting this option is helpful if you want to publish a new UI bundle for testing purposes (production builds of the DataStax documentation are only configured to consume the latest _non-pre-release_ UI bundle).\nYou can then edit the release in the future to remove the *Pre-release* label, if desired.\n+\nCAUTION: If you do not check this box, then the release is immediately promoted to *Latest*, and all DataStax docs will consume the new UI bundle the next time they are built.\n\n. Update the `:current-release:` attribute in the header of this README to reference the tag of the latest bundle (if it is not pre-release), then commit that update to the repository.\n\n== Hero block\nThere are two files that need to be updated in order to include the hero block in a page\n\n* helios-gcs-heroBlock.css\n* The .adoc file you want to add the hero block\n\n=== Define Background css\n\n. To define the hero block background, it needs to be done in the `helios-gcs-heroBlock.css` file located under /gcx/styles/src/css/  path\n. It requires to set the class identifier name/value and the path to the background image which can be an svg file.\n. The class identifier name/value would be any meaningful value you would like to use to identify the background image.\n.. The identifier name will be used to reference the background image in the .adoc where the hero will be setup.\n.. If the identifier name is not defined, it will use the default setup image.\n\nFor the below code portion .dsHeroBlock, .dsHeroBlock[data-banner=\"default\"] would be the default image to set in case no identifier or \"default\" identifier is set\n-----\n.dsHeroBlock,\n.dsHeroBlock[data-banner=\"default\"] {\n    background-image: url('../img/hero-banner-1.svg');\n    background-size: cover;\n    color: white;\n    font-family: 'Roboto', sans-serif;\n  }\n-----\n\nTo set a specific background image, it will be done by setting the identifier value and the image path\n----\n.dsHeroBlock[data-banner=\"alternative\"]{\n  background-image: url('../img/hero-banner-2.svg');\n}\n----\n\n=== Define the hero block in a .adoc file\nThe structure to set a hero block in an `.adoc` file is as shown in the code block below. This will add the hero block to the top of the page which will have a background, title, content.\n\n. Hero Block background (class=\"dsHeroBlock\")\n.. This is set by adding `\u003cdiv class=\"dsHeroBlock\" data-banner=\"alternative\"\u003e` where the \"data-banner identifier will be the name especified for the image in the `helios-gcs-heroBlock.css`  file.\n. [.hero.title]\n.. This tag is used to set the hero banner title\n. [.hero.content]\n.. This tag is used to set the hero banner content under the title.\n\n----\n++++\n\u003cdiv class=\"dsHeroBlock\" data-banner=\"alternative\"\u003e\n++++\n\n[.hero.title]\nDocumentation Home\n\n[.hero.content]\nLorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.\n\n++++\n\u003c/div\u003e\n++++\n----\n\n\n== Copyright and license\n\n=== Antora Default UI\n\nCopyright (C) 2017-present OpenDevise Inc. and the Antora Project.\n\nUse of this software is granted under the terms of the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License Version 2.0] (MPL-2.0).\n\n=== Branding and design\n\nCopyright (C) {url-datastax}[DataStax] 2021-present.\nAll rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friptano%2Fantora-ui-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friptano%2Fantora-ui-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friptano%2Fantora-ui-docs/lists"}