{"id":28925645,"url":"https://github.com/redpanda-data/docs-ui","last_synced_at":"2026-05-20T17:01:05.802Z","repository":{"id":128697419,"uuid":"610186192","full_name":"redpanda-data/docs-ui","owner":"redpanda-data","description":"UI project for the Redpanda documentation site.","archived":false,"fork":false,"pushed_at":"2026-05-12T10:26:50.000Z","size":34455,"stargazers_count":4,"open_issues_count":5,"forks_count":7,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-05-12T12:32:39.756Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/redpanda-data.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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-06T09:12:35.000Z","updated_at":"2026-04-29T15:57:50.000Z","dependencies_parsed_at":"2026-01-25T12:05:50.834Z","dependency_job_id":null,"html_url":"https://github.com/redpanda-data/docs-ui","commit_stats":null,"previous_names":["redpanda-data/docs-ui"],"tags_count":340,"template":false,"template_full_name":null,"purl":"pkg:github/redpanda-data/docs-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redpanda-data%2Fdocs-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redpanda-data%2Fdocs-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redpanda-data%2Fdocs-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redpanda-data%2Fdocs-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redpanda-data","download_url":"https://codeload.github.com/redpanda-data/docs-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redpanda-data%2Fdocs-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33268261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-20T15:12:43.734Z","status":"ssl_error","status_checked_at":"2026-05-20T15:12:42.300Z","response_time":356,"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":"2025-06-22T11:09:55.641Z","updated_at":"2026-05-20T17:01:05.761Z","avatar_url":"https://github.com/redpanda-data.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Redpanda Documentation UI\n:url-docs: https://docs.redpanda.com\n:url-org: https://github.com/redpanda-data\n:ui-project: docs-ui\n:url-ui: {url-org}/{ui-project}\n:url-extensions: {url-org}/docs-extensions-and-macros\n:url-site: {url-org}/docs-site\n:url-redpanda: https://redpanda.com\n:url-antora: https://antora.org/\n:hide-uri-scheme:\n:url-contributing: {url-site}/blob/main/meta-docs/CONTRIBUTING.adoc\n:url-netlify: https://netlify.com\n:url-netlify-docs: https://docs.netlify.com\n:url-antora-docs: https://docs.antora.org\n:url-redoc: https://github.com/Redocly/redoc\n:url-nodejs: https://nodejs.org/en/download\n:url-git: https://git-scm.com/downloads\n:idprefix:\n:idseparator: -\n:experimental:\nifdef::env-github[]\n:important-caption: :exclamation:\n:note-caption: :paperclip:\nendif::[]\n:toc:\n:toc-title: Contents\n\ntoc::[]\n\n\nThis project is used to develop and distribute the UI for the {url-site}[Redpanda documentation site].\nThe UI bundle this project produces is intended to be used with {url-antora}[Antora].\nThe UI bundle contains the HTML templates, CSS, JavaScript, fonts, and site-wide images.\nThe rest of the material for the documentation site comes from the {url-site}[playbook repository] and content repositories.\n\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: {url-ui}/releases/latest/download/ui-bundle.zip\n----\n\n== Development Quickstart\n\nIn this section, you learn how to set up the UI project, preview it locally, and bundle it for use with Antora.\n\n=== Prerequisites\n\nTo preview and bundle the UI, you need the following software on your computer:\n\n==== git\n\nMake sure you have git installed.\n\n[,bash]\n----\ngit --version\n----\n\nIf not, {url-git}[download and install] the git package for your system.\n\n==== Node.js\n\nYou must have {url-nodejs}[Node.js] 18 or higher installed on your machine.\n\n[,bash]\n----\nnode --version\n----\n\nIf this command fails, you don't have Node.js installed.\n\n==== Gulp CLI\n\nYou'll need the Gulp command-line interface (CLI) to run the build.\nThis package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project.\n\nYou should 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[,bash]\n----\nnpm install -g gulp-cli\n----\n\nVerify the Gulp CLI is installed and on your PATH by running:\n\n[,bash]\n----\ngulp -v\n----\n\nNow that you have the prerequisites installed, you can fetch and build the UI project.\n\n==== Golang\n\nPart of the bundle process uses Golang (Go) to build a WebAssembly (`.wasm`) file. As a result, you need Go installed on your machine.\n\nVerify that Go is installed:\n\n[,bash]\n----\ngo version\n----\n\nIf Go is not installed, https://go.dev/doc/install[download and install it].\n\nNOTE: For Netlify previews, we set the `GO_VERSION` https://docs.netlify.com/configure-builds/manage-dependencies/#go[environment variable] to 1.23.4 to match the version in the `go.mod` file.\n\n=== Clone and Initialize the UI Project\n\nClone the UI project using git:\n\n[,bash,subs=attributes+]\n----\ngit clone {url-ui}\ncd {ui-project}\n----\n\nThe example above clones the Redpanda docs UI project and then switches to the project directory on your filesystem.\nStay in this project directory when executing all subsequent commands.\n\nUse npm to install the project's dependencies inside the project.\nIn your terminal, execute the following command:\n\n[,bash]\n----\nnpm install\n----\n\nThis command installs the dependencies listed in `package.json` into the `node_modules/` directory inside the project.\nThis directory does not get included in the UI bundle and should _not_ be committed to the source control repository.\n\n=== Preview the UI\n\nThe UI project is configured to preview offline.\nThe files in the `preview-src/` directory provide the sample content that allows you to see the UI in action.\nIn this directory, you'll primarily find pages written in AsciiDoc.\nThese pages provide a representative sample and kitchen sink of content from the real site.\n\nTo build the UI and preview it in a local web server, run the `preview` command:\n\n[,bash]\n----\ngulp preview\n----\n\nYou'll see a URL listed in the output of this command:\n\n....\n[17:32:55] Starting 'preview:serve'...\n[17:32:55] Starting server...\n[17:32:55] Server started http://localhost:5252 and http://192.168.1.3:5252\n[17:32:55] 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 `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==== Preview Online\n\nYou can share a preview of the UI online by submitting a pull request to GitHub.\nThe repository is configured to create a deploy preview on Netlify for every pull request.\n\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[,bash]\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 `build/ui-bundle.zip`.\nYou can point Antora at this bundle using the `--ui-bundle-url` command-line option or in the `ui.bundle.url` property of the playbook file.\n\n== Control the Visual Appearance of Pages\n\nTo control the visual appearance of pages, the UI bundle provides a CSS stylesheet (for changing the CSS style rules) and any number of layouts in the form of Handlebars templates (for changing the HTML).\nAlthough most styles are used on all pages, it's possible to configure styles to target certain pages based on the layout.\nThis section will introduce these various options and explain how they work.\n\n=== UI Layouts\n\nThe most drastic way to change the appearance of the page is to change the HTML.\nThe HTML is controlled by layouts, which are Handlebars templates located in [.path]_src/layouts_.\nA layout typically includes partials, located in [.path]_src/partials_, which are reusable template fragments.\nPartials may, in turn, include other partials.\n\nThis project currently has five layouts:\n\n* default.hbs\n* 404.hbs\n* home.hbs\n* index.hbs\n* search.hbs\n\nIf a page doesn't specify a layout, the `default.hbs` layout is used.\n\nTo specify a layout, the page file must declare the `page-layout` document attribute in the AsciiDoc header.\nThe value of that attribute should match the stem of the layout file (the filename minus the file extension, such as `home`).\n\nFor example, the home page declares the following document attribute in the AsciiDoc header:\n\n[source,asciidoc]\n----\n= Redpanda Documentation\n:page-layout: home\n----\n\nIn this case, Antora will select the `home.hbs` layout for this page instead of `default.hbs`.\nUsing a dedicated layout affords a lot of control over what gets displayed on this page.\nEvery layout has access to the same UI model.\n\nThe home page likely requires additional styles that are only relevant to that page.\nYou can organize these styles inside a namespace by adding a dedicated class to the `\u003cbody\u003e` tag.\nIn fact, that's what the `home.hbs` layout currently does.\n\n[source,html]\n----\n\u003cbody class=\"home\"\u003e\n  ...\n\u003c/body\u003e\n----\n\nYou can now define styles that are scoped to that page as follows:\n\n[source,css]\n----\n.home h1,\n.home h2,\n.home h3 {\n  line-height: 1.2;\n  margin: 0;\n}\n----\n\nTo make these styles easier to find and manage, they should be organized in a dedicated file `src/css/home.css` and included in the master `src/css/site.css` file, which is how this project is currently configured.\n\nWhen you run the preview, you can see the home page by visiting the URL \\http://localhost:5002/home.html.\n\n=== Content Preview\n\nYou can create an arbitrary number of pages for the preview site.\nTo make a page, create a new AsciiDoc file inside the `preview-src` directory.\nYou can then access the page in the preview site using the URL pattern \\http://localhost:5252/\u003cstem\u003e.html, where `\u003cstem\u003e` is the stem of the source file (the filename minus the file extension).\n\nThese preview pages serve the purpose of testing the page layout and content styling.\nEach page may declare a layout, role, or both.\n\nThe only caveat is that, at the moment, every page provides the same UI model (with a few exceptions).\nThe model is defined in `preview-src/ui-model.yml` file.\nThe exceptions include the layout, role, title, contents, and, in the case of home.adoc, the component, which get updated dynamically by the build.\n\nFor information about what goes in the UI model, refer the https://docs.antora.org/antora-ui-default/templates/[Handlebars templates page] in the Antora documentation.\n\n== Integrations\n\n=== Algolia Search\n\nThis UI provides integration with Algolia search.\nThe Algolia client is configured in the files `src/partials/algolia-script.hbs` and `src/layouts/search.hbs`.\nYou can test the search directly from the preview site by setting the following environment variables in your shell:\n\n* `ALGOLIA_APP_ID` - the application ID that hosts the search index\n* `ALGOLIA_API_KEY` - your API key for Algolia\n* `ALGOLIA_INDEX_NAME` - the name of the index\n\nYou can point to any index that is publicly accessible.\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.\nThis project provides a GitHub Action that fully automates the release.\n\nWhenever you push a new tag to this repository, the GitHub Action will generate a new release and bundle the UI before publishing the bundle to the releases section of the repository on GitHub.\nThe bundle can then be downloaded using a unique URL, accessible from the release page.\nYou can see a list of all past releases on the {url-ui}/releases[releases page].\n\n== Troubleshooting\n\nIf you’re trying to bundle the UI on Windows, Visual Studio Code can output this error message: `Cannot be loaded because running scripts is disabled on this system`. To fix this problem, follow the steps in https://stackoverflow.com/a/67420296[this post].\n\n== Copyright and License\n\n=== Software\n\nThe software in this repository (build scripts, JavaScript files, Handlebars templates, foundation CSS, utility icons, etc) is part of the {url-antora}[Antora project].\nAs such, the use of the 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-redpanda}[Redpanda] 2024.\nAll rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredpanda-data%2Fdocs-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredpanda-data%2Fdocs-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredpanda-data%2Fdocs-ui/lists"}