{"id":13607898,"url":"https://github.com/couchbase/docs-ui-old","last_synced_at":"2025-10-07T15:22:04.258Z","repository":{"id":66135644,"uuid":"138940143","full_name":"couchbase/docs-ui-old","owner":"couchbase","description":"Produces the UI bundle used by the Couchbase documentation site.","archived":false,"fork":false,"pushed_at":"2020-08-04T16:50:55.000Z","size":1698,"stargazers_count":12,"open_issues_count":12,"forks_count":27,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-07T13:38:04.697Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cb-docs-ui.netlify.com/","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-06-27T22:41:33.000Z","updated_at":"2021-02-01T22:59:28.000Z","dependencies_parsed_at":"2023-03-13T20:30:46.320Z","dependency_job_id":null,"html_url":"https://github.com/couchbase/docs-ui-old","commit_stats":null,"previous_names":[],"tags_count":269,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fdocs-ui-old","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fdocs-ui-old/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fdocs-ui-old/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fdocs-ui-old/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase","download_url":"https://codeload.github.com/couchbase/docs-ui-old/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248581160,"owners_count":21128112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-08-01T19:01:22.621Z","updated_at":"2025-10-07T15:21:59.192Z","avatar_url":"https://github.com/couchbase.png","language":"CSS","funding_links":[],"categories":["CSS"],"sub_categories":[],"readme":"= Couchbase Documentation UI\n// Variables:\n:current-release: v269\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: couchbase/docs-ui\n:url-project: https://github.com/{project-repo-name}\n:url-site: https://docs.couchbase.com\n:url-repo: git@github.com:{project-repo-name}.git\n:url-preview: https://cb-docs-ui.netlify.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-couchbase: https://couchbase.com\n\nifdef::badges[]\nimage:https://img.shields.io/github/release/{project-repo-name}.svg[Latest Release,link={url-project}/releases/download/{current-release}/ui-bundle.zip]\nendif::[]\n\ntoc::[]\n\nThis project is used to develop and distribute the UI for the {url-site}[Couchbase documentation site].\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.\nThe rest of the material for the documentation site comes from the content repositories.\n\nYou can view a preview of this UI online at {url-preview}.\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-project}/releases/download/{current-release}/ui-bundle.zip\n----\n\nRead on to learn how to develop the UI.\n\n== Development Quickstart\n\nThis section offers a basic tutorial to 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* {url-git}[git] (command: `git`)\n* {url-node}[Node 10] (command: `node`)\n* {url-gulp}[Gulp CLI] (command: `gulp`)\n\n==== git\n\nFirst, make sure you have git installed.\n\n $ git --version\n\nIf not, {url-git-dl}[download and install] the git package for your system.\n\n==== Node 10\n\nNext, make sure that you have Node 10 installed.\n\n $ node -v\n\nIf this command fails with an error, you don't have Node installed.\nIf the command doesn't report a Node 10 version (e.g., v10.15.3), then you don't have a suitable version of Node installed.\n\nWhile you can install Node from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to install and manage Node.\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 10 using the following command:\n\n $ nvm install 10\n\nYou can switch to this version of Node at any time using the following command:\n\n $ nvm use 10\n\nTo make Node 10 the default in new terminals, type:\n\n $ nvm alias default 10\n\nNow that you have Node 10 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.\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 $ npm install -g gulp-cli\n\nIf you prefer to install global packages using Yarn, run this command instead:\n\n $ yarn global add gulp-cli\n\nVerify the Gulp CLI is installed and on your PATH by running:\n\n $ gulp -v\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 $ git clone {url-project} \u0026\u0026\n   cd \"`basename $_`\"\n\nThe example above clones the Couchbase docs UI project and then switches to the project folder on your filesystem.\nStay in this project folder 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 $ npm install\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 to the source control repository.\n\n=== Preview the UI\n\nThe 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\nTo build the UI and preview it in a local web server, run the `preview` command:\n\n $ gulp preview\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.\nHere's how that process works:\n\n. Fork the repository on GitHub (only has to be done once).\n. Create a local branch.\n. Make changes to the UI.\n. Commit your changes to that branch.\n. Push that branch to your fork (on GitHub).\n. Submit a pull request from the branch you pushed to your fork.\n. Wait for deploy/netlify check to say \"`Deploy preview ready`\" on the pull request page.\n. Click on the \"`Details`\" link under \"`Show all checks`\" on the pull request page.\n. View your changes in the deploy preview or share the URL with others.\n\nThe deploy preview works because there is a webhook on the repository that pings \\https://api.netlify.com/hooks/github for the following events: push, pull_request, delete_branch.\nNetlify then runs the command specified in netlify.toml, deploys the site, and allocates a temporary URL for it.\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 $ gulp bundle\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 (e.g., `--ui-bundle-url=../docs-ui/build/ui-bundle.zip`).\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 either based on the layout or page role.\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 three layouts:\n\n* default.hbs\n* 404.hbs\n* home.hbs\n\nIf a page doesn't specify a layout, the [.path]_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, e.g., `home`).\n\nFor example, the home page declares the following document attribute in the AsciiDoc header:\n\n[source,asciidoc]\n----\n= Welcome to the Couchbase Docs!\n:page-layout: home\n----\n\nIn this case, Antora will select the [.path]_home.hbs_ layout for this page instead of [.path]_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 for 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 [.path]_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 [.path]_src/css/home.css_ and included into the master [.path]_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:5252/home.html.\n\nThe [.path]_404.hbs_ layout is similar to other layouts, except Antora selects it automatically to make the 404 page (404.html).\nFor this page, the `page` variable in the UI model is reduced to `page.layout` and `page.title`.\nNone of the other data in the `page` variable is applicable for this page.\n\nWhen you run the preview, you can see the 404 page by visiting the URL \\http://localhost:5252/404.html.\n\n=== Page Roles\n\nCreating a new layout is powerful, but incurs a lot of maintenance overhead.\nIf you're only looking to tweak the visual appearance of the article region of the page, perhaps to support custom UI components, you can instead define a page role.\n\nA page role is a special role that can be assigned per page that's typically applied directly to the main article.\nIt's a way to activate CSS that is scoped to a given page or group of pages.\n\nTo apply a page role, the AsciiDoc file for the page must declare the `page-role` attribute in the AsciiDoc document header.\nFor example, the Starter Kits page declares the `tiles` role as follows:\n\n[source,asciidoc]\n----\n= Starter Kits\n:page-role: tiles\n----\n\nThe value of this attribute is added by the [.path]_src/css/body.hbs_ template to the class attribute of the `.body` element.\n\n[source,html]\n----\n\u003cdiv class=\"body container{{#if page.attributes.role}} {{page.attributes.role}}{{/if}}\"\u003e\n  ...\n\u003c/div\u003e\n----\n\nTherefore, setting the `page-role` attribute to `tiles` activates any CSS under the `.body.tiles` selector.\nFor example:\n\n[source,css]\n----\n.body.tiles .doc {\n  display: flex;\n  flex-wrap: wrap;\n  margin-right: -1.25rem;\n}\n----\n\nThese and other styles organize the sections of the page into tiles.\nWhen you run the preview, you can see the tiles role in action by visiting the URL \\http://localhost:5252/tiles.html.\n\nYou can create as many of these roles as you like simply by adding CSS scoped to the name of a role.\n\n=== Tabs\n\nThe playbook for the Couchbase documentation includes a tabs block extension.\nThe extension takes care of converting the AsciiDoc for the tabs to HTML.\nThe UI provides the interaction (JavaScript) and styles (CSS) that power these tabs.\n\nYou can find the JavaScript for the tabs in the file [.path]_src/js/05-tabset.js_.\nYou can find the styles for the tabs in the file [.path]_src/css/doc.css_.\nThe preview site provides an example of these tabs in the file [.path]_preview-src/index.adoc_.\nNote that authors should never enter the HTML for tabs directly, but it is entered this way in the preview site to make it easier to work with.\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 [.path]_preview-src_ folder.\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 [.path]_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 file [.path]_src/partials/footer-scripts.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 (optional if you're using docsearch)\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=== JIRA Feedback\n\nThis UI provides integration with JIRA feedback.\nThe JIRA feedback widget is configured in the file [.path]_src/partials/footer-scripts.hbs_.\nYou can test the feedback widget directly from the preview site by setting the `FEEDBACK_BUTTON=true` environment variable in your shell.\n\nThe configuration for the widget is currently hardcoded into the partial template.\n\n== View Latest and Canonical URL\n\nThis section documents the logic used to compute the URL for the View Latest button and the canonical URL.\n\n=== View Latest\n\nIf the version of the current page does not match the latest version of the component (i.e., product), a banner is displayed to the visitor.\nIf the version is a prerelease, the banner states that you're viewing a prerelease version.\nIf the version is an older stable release, the banner states that a newer version is available.\nOn the banner offers a button named \"View Latest\" that directs the visitor to the latest version.\n\nThe \"View Latest\" button tries to preserve the current page when switching versions.\nIf the page is no longer available, then the button directs the user to the start page for the component.\n\nThe URL for the \"View Latest\" button is computed by the latest-page-url helper.\nHere's the logic that the helper uses:\n\n* If the current page is found in the latest version, the latest page URL resolves to the URL of that page.\nFor example, the latest page URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/6.5/introduction/intro.html (assuming 6.5 is the latest version)\n ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word \"current\".\nFor example, the latest page URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/current/introduction/intro.html\n* If the current page is not found in the latest version, but the page is claimed by an alias, the latest page URL resolves to the URL of the page to which the alias points.\nFor example, the latest page URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/6.5/manage/management-overview.html (assuming 6.5 is the latest version)\n ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word \"current\".\nFor example, the latest page URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/current/manage/management-overview.html\n* If neither the current page or an alias is found in the latest version, the latest page URL resolves to the component start page.\n ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word \"current\".\n\nIf the current page is in the archive site and the latest version is in the production site, then the latest page URL will point to the production site.\nIn this case, the version segment will only be replaced with \"current\" if the PRIMARY_SITE_SUPPORTS_CURRENT_URL=true environment variable is set.\n\n=== Canonical URL\n\nThe canonical URL differs slightly from the URL for the \"View Latest\" button in that if the page cannot be found in the latest version, it instead resolves to the newest version of the page.\nThe canonical URL can resolve to the current URL (if the current URL is the canonical URL).\n\nThe canonical URL is computed by the canonical-url helper.\nHere's the logic that the helper uses:\n\n* If the site.url is not set to an absolute path, no value is returned.\n* If the current page is found in the latest version, the canonical URL resolves to the URL of that page.\nFor example, the canonical URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/6.5/introduction/intro.html (assuming 6.5 is the latest version)\n ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word \"current\".\nFor example, the canonical URL for https://docs.couchbase.com/server/6.0/introduction/intro.html resolves to https://docs.couchbase.com/server/current/introduction/intro.html\n* If the current page is not found in the latest version, but the page is claimed by an alias, the canonical URL resolves to the URL of the page to which the alias points.\nFor example, the canonical URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/6.5/manage/management-overview.html (assuming 6.5 is the latest version)\n ** If the SUPPORTS_CURRENT_URL=true environment variable is set, the version segment in the URL is replaced with the word \"current\".\nFor example, the canonical URL for https://docs.couchbase.com/server/5.5/admin/ui-intro.html resolves to https://docs.couchbase.com/server/current/manage/management-overview.html\n* If neither the current page or an alias is found in the latest version, the current URL resolves to the newest version of the page (which could be the current page).\nFor example, the canonical URL for https://docs.couchbase.com/server/4.0/architecture/cluster-ram-quotas.html resolves to https://docs.couchbase.com/server/4.1/architecture/cluster-ram-quotas.html\n ** If the SUPPORTS_CURRENT_URL=true environment variable is set, it has no affect on this case.\n\nIf the current page is in the archive site and the latest version is in the production site, then the canonical URL will point to the production site.\nIn this case, the version segment will only be replaced with \"current\" if the PRIMARY_SITE_SUPPORTS_CURRENT_URL=true environment variable is set and the newest version of the page is the latest version of the component.\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 Gulp build task, appropriately named *release*, that fully automates the release.\n\nThe release task tags the repository and publishes 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-project}/releases[releases page].\n\n=== Release Task Workflow\n\nReleasing the UI bundle consists of the following tasks:\n\n. Pack the UI bundle.\n. Tag the git repository using the next version number in the sequence (e.g., v100 after v99)\n. Create a GitHub release from that git tag.\n. Attach the UI bundle to that release as an asset in zip format.\n. Update the README to reference the URL of the lastest bundle and commit that update to the repository.\n\nFortunately, you don't have to do any of these steps yourself.\nThese steps are fully automated by the `gulp release` task.\nIn fact, you don't even have to run the `gulp release` task manually.\nWhen a commit is pushed to the master branch of the repository, it triggers the CI job named *release-docs-ui-bundle*, which executes the `gulp release` task using pre-configured credentials.\n\nIMPORTANT: A release will only be made if the project validates.\nTo validate the project, run `gulp pack` before pushing your changes to GitHub.\n\nThe release-docs-ui-bundle CI job is already configured, so there's nothing you need to do to make automated release work.\nAll you have to do is commit your changes and push those commits to the master branch of the git repository.\nA few seconds later, a new bundle will be available for use with Antora.\nRun `git pull` to retrieve the updated README that includes the new URL.\n\nTIP: If you want to commit a change to master without making a release, add the string `[skip ci]` to the end of the commit message.\n\nThe next two sections document how the CI job is set up an configured.\n\n=== Release Task Prerequisites\n\nIn addition to the \u003c\u003cPrerequisites\u003e\u003e covered above, you'll need a personal access token for the automated GitHub account, cb-docs-robot, so it has permission to make changes to the repository on GitHub.\nThe cb-docs-robot account will need at least write access to the {url-project} repository, though admin access is recommended.\n\nStart by creating a https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/[personal access token] for the cb-docs-robot user.\nThe `release` task relies on this token to interact with the GitHub API to create the tag, create the release, and upload the asset.\nThe token must have the public_repo scope.\nNo other scopes are required (as long as the cb-docs-robot account has write access to the repository).\nNext, copy the token generated and store it as a _Secret text_ Jenkins credential as follows:\n\n[unstyled]\n* _Kind:_ Secret text\n* _Scope:_ System (Jenkins and nodes only)\n* _Secret:_ \u003center-token-value\u003e\n* _ID:_ docs-robot-api-key\n* _Description:_ GitHub API key for docs robot\n\nThe token gets passed to the task as the `GITHUB_API_TOKEN` environment variable.\nIn the CI job configuration, covered in the next section, you'll learn how this token gets transferred from the Jenkins credential to the `GITHUB_API_TOKEN` environment variable when the build executes.\n\n=== CI Job Configuration\n\nJenkins is used to execute the CI job that publishes the UI bundle.\nThe job is named *release-docs-ui-bundle* and can be found under the *Antora* folder in the Jenkins server managed by the Couchbase docs team.\nThis section describes in detail how that job has been configured in case it must be recreated.\n\nThe release is performed by the cb-docs-robot GitHub account, which interacts with GitHub entirely using the GitHub API.\nThe release script authenticates with the GitHub API as the cb-docs-robot user using a personal access token retrieved from the `GITHUB_API_TOKEN` environment variable.\n\nCreate a new CI job from the Pipeline project template.\nOn the configuration screen, select or populate the following settings:\n\n.Configuration details for the Antora/release-docs-ui-bundle CI job\n====\nGeneral::\n* _Project name:_ `release-docs-ui-bundle`\n* _Description:_ Packs, tags, and releases the UI bundle whenever a non-ignored commit is pushed to the master branch of this repository.\n* [x] GitHub project\n ** _Project url:_ `pass:a[{url-project}]`\nBuild Triggers::\n* [x] GitHub hook trigger for GITScm polling\nPipeline Definition::\n* Pipeline script from SCM\nSCM::\n* [x] Git\n ** _Repository URL:_ `pass:a[{url-project}]`\n ** _Branches to build \u003e Branch Specifier:_ `*/master`\n ** Additional Behaviours\n  *** *Advanced clone behaviours*\n   **** [ ] Fetch tags\n   **** [x] Honor refspec on initial clone\n   **** [x] Shallow clone\n   **** Shallow clone depth: `3`\n  *** *Polling ignores commits with certain messages*\n   **** _Excluded Messages:_ `+(?s)(?:Release v\\d+|.*\\[skip .+?\\]).*+`\n* _Script Path:_ `Jenkinsfile`\n* [x] Lightweight checkout\n====\n\nIn the Jenkinsfile, a credentials function is used to binds the value of the personal access token for the cb-docs-robot read from the specified Jenkins credential to the `GITHUB_API_TOKEN` environment varaible.\nThis environment variable is used by the release task to authenticate against the GitHub API as the cb-docs-robot user.\n\nThe heart of the build are the `sh` commands defined in the Jenkinsfile.\nSince Jenkins retains the workspace between runs, it's necessary to start by removing artifact left behind by previous builds.\nNext, the dependencies are installed or updated by the call to `npm install`.\nThanks to the package cache, npm finds most of the dependencies locally and thus the call to it is very fast.\nFinally, the job delegates to Gulp to perform the release steps described in \u003c\u003cRelease Task Workflow\u003e\u003e.\n\nOnce the CI job runs and a new UI bundle is available, you can update the URL of the UI bundle in the Antora playbook file.\nSee \u003c\u003cUsage\u003e\u003e for details.\n\n=== Webhook / Trigger\n\nThe build trigger requires coordination with the {url-project} repository on GitHub.\nSpecifically, the GitHub repository must be configured to ping the Jenkins webhook whenever a commit comes in.\n\nJenkins will attempt to set up this link for you when you create the job using the GitHub API key specified under menu:Jenkins[Manage Jenkins \u003e Configure System \u003e GitHub \u003e GitHub Servers].\nIn order for this to work, the cb-docs-robot account must temporarily have admin access to the {url-project} repository.\nIf Jenkins fails to establish that link, you'll need to set it up manually, which is covered below.\n\nIf you have admin access to the repository on GitHub, you can see the details of this webhook by navigating to {url-project}/settings/hooks.\nHere are the details of that webhook:\n\n====\nPayload URL:: JENKINS_URL/github-webhook/ \u003c1\u003e\nContent type:: application/json\nSecret:: _hidden_\nWhich events would you like to trigger this webhook?::\n* [x] Just the `push` event\n\n{empty}\u003c1\u003e JENKINS_URL is a placeholder for the real URL of the Jenkins server.\n====\n\nYou can also find a list of recent deliveries on that screen.\n\n==== Set Up the Webhook Manually\n\nIf Jenkins doesn't have proper permissions to create the webhook on GitHub, you'll need to configure it manually.\nTo set up this ping (i.e., webhook), navigate to the menu:Settings[Webhooks] page of the GitHub repository.\nClick btn:[Add webhook], enter the following URL in the Payload URL field, then click btn:[Add webhook].\n\n[subs=attributes+]\n JENKINS_URL/git/notifyCommit?url={url-project}\u0026branches=master\n\n(Replace JENKINS_URL with the URL of the Jenkins server).\n\nNo secret is required (as this URL does not require authentication).\n\nUpdate the job configuration to use *Poll SCM* with an empty schedule instead of *GitHub hook trigger for GITScm polling*.\nThat will allow this ping to work and prevent Jenkins from showing any warnings.\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, 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-couchbase}[Couchbase] 2018-2019.\nAll rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase%2Fdocs-ui-old","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase%2Fdocs-ui-old","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase%2Fdocs-ui-old/lists"}