{"id":24761833,"url":"https://github.com/cumulocity-iot/c8y-docs","last_synced_at":"2025-10-11T09:31:17.445Z","repository":{"id":36982418,"uuid":"379584201","full_name":"Cumulocity-IoT/c8y-docs","owner":"Cumulocity-IoT","description":"Cumulocity IoT guides and documentation","archived":false,"fork":false,"pushed_at":"2024-10-29T09:43:52.000Z","size":868164,"stargazers_count":19,"open_issues_count":34,"forks_count":30,"subscribers_count":14,"default_branch":"develop","last_synced_at":"2024-10-29T09:54:45.805Z","etag":null,"topics":["cumulocity-documentation","cumulocity-iot","hugo","iot-analytics"],"latest_commit_sha":null,"homepage":"","language":"SCSS","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/Cumulocity-IoT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-23T11:46:11.000Z","updated_at":"2024-10-28T09:59:36.000Z","dependencies_parsed_at":"2024-03-04T07:52:32.812Z","dependency_job_id":"8f4fee46-2254-4659-ac53-fa792c83f0e1","html_url":"https://github.com/Cumulocity-IoT/c8y-docs","commit_stats":null,"previous_names":["cumulocity-iot/c8y-docs"],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fc8y-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fc8y-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fc8y-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fc8y-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cumulocity-IoT","download_url":"https://codeload.github.com/Cumulocity-IoT/c8y-docs/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236072286,"owners_count":19090409,"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":["cumulocity-documentation","cumulocity-iot","hugo","iot-analytics"],"created_at":"2025-01-28T19:19:41.413Z","updated_at":"2025-10-11T09:31:07.433Z","avatar_url":"https://github.com/Cumulocity-IoT.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cumulocity documentation website\n\n\u003chttps://cumulocity.com/guides\u003e - releases 10.18 and older\n\u003chttps://cumulocity.com/docs\u003e - CD and yearly releases\n\n**Built with [Hugo](https://gohugo.io/)** (version 0.92.1)\n\n## Development environment\n\n- Clone the repository.\n- Install Hugo by using snap `snap install hugo --channel=extended`.\n- Open a terminal window in the project directory and type `hugo server`. Specify the subdirectory that contains your content, for example http://localhost:1313/guides/users-guide/. Specifying only http://localhost:1313/guides results in a 404 error.\n\nDetails are described in the \"How to contribute to the Cumulocity documentation\" process document. Contact the Cumulocity documentation team for access.\n\n## Structure for /guides (for releases 10.18 and older)\n\nThe Cumulocity documentation website architecture has the following structure:\n\n- 1st level  - for example, *\u003chttp://cumulocity.com/guides/users-guide/\u003e*\n  - 2nd level - renders as a single page, for example *\u003chttp://cumulocity.com/guides/users-guide/administration/\u003e*\n    - Anchor section - anchor tag in the subsection page, for example *\u003chttp://cumulocity.com/guides//users-guide/administration/#managing-permissions\u003e*\n\nThe website is built with a mix of front matter and directory structure.\n\n\n## Structure - /docs (for CD and yearly releases)\n\nThe Cumulocity documentation website architecture has the following structure:\n\n- 1st level  - for example, *\u003chttp://cumulocity.com/docs/platform_administration\u003e*\n  - 2nd level - for example *\u003chttp://cumulocity.com/docs/platform_administration/standard-tenant/\u003e*\n    - 3rd level - renders as a single page, for example *\u003chttp://cumulocity.com/docs/standard-tenant/managing-permissions\u003e*\n      - Anchor section - anchor tag in the subsection page, for example *\u003chttp://cumulocity.com/docs/standard-tenant/managing-permissions/#global-roles\u003e*\n\nThe website is built with a mix of front matter and directory structure.\n\n\n## Adding content\n\n### Add a new section\n\nNote that in the new documentation structure (/docs) adding level 1 or level 2 sections is restricted to the admin users of the c8y-docs repo. If you want to add a new section in these levels contact the documentation team.\n\nBefore adding a new section, check if the content fits in any of the available sections.\n\nA new section is defined by a Markdown file with the following front matter:\n\n```yaml\n---\ntitle: My new section # add the section title\nbundle: new-section # add the directory holding the section pages\nicon: \"c8y-icon c8y-icon-tools\" # use either fontawesome or c8y-icons\ntype: root # don't change\nlayout: root # don't change\nweight: 90 # order the section in the section dropdown in ascending order\n---\n```\nGrab the icon classes in the [Styleguide](https://styleguide.cumulocity.com/#/icons/cumulocity).\n\n### Add the section root directory\n\nAll guides are stored in the `content` directory. To add a new section, create a directory here and name it with the `bundle` value set in the front matter.\n\n### Add a subsection\n\nInside the newly created directory create a Markdown file with the name you wish to use as a URL — for example `introduction.md` with the following front matter:\n\n```yaml\n---\ntitle: Introduction to Cumulocity # the page title\nlayout: bundle # don't change\nweight: 10 # set the position of the page within the section in ascending order\naliases: # if needed, add the redirects here, otherwise remove this\n  - /concepts/introduction-to-cumulocity/\n  - /concepts/introduction-to-cumulocity.html\n---\n# add optional content as Markdown\nCumulocity gives you very fast visibility and control over your remote assets, be these houses, cars, machines or any other assets that you need to manage.\n```\n\nIf you're looking to have a short page without anchors, you're good to go, but if you want to add multiple subsections with anchors then proceed to the next step.\n\nWhen adding multiple subsections, the content provided in this file will be rendered as a lead in the top of the page.\n\n### Add blocks of content with anchors to a page\n\nTo display multiple blocks of content and provide anchor links to display in the navigator, you'll have to follow these steps:\n\n  1. Add a directory with the exact same name as the Markdown file adding the suffix `-bundle`, e.g. `introduction-bundle`.\n\n\u0026nbsp;\n\n  2. Add a `index.html` file into the new directory with the following front matter:\n\n```yaml\n---\ntitle: Introduction # not important as we won't use it, but we need the title\nheadless: true # states that all content inside this directory is just a resource to be used in another page\n---\n```\n\n  3. Add a Markdown file for each block of content with the following front matter:\n\n```yaml\n---\ntitle: Overview # will be used as anchor, i.e. guides/users-guide/introduction/#overview\nweight: 10 # to set the position in the page\n---\n\n## Add content as Markdown or HTML\n\n* Certified hardware kits and software libraries you can use to bring your remote assets into the cloud.\n* Device management, data visualization and remote control functionality through the web.\n* Rapid customization of the above through [real-time processing](/concepts/realtime) and [Cumulocity applications](/concepts/applications).\n* APIs for extending the existing functionality or interfacing Cumulocity with your other IT services such as ERP or CRM systems. Cumulocity can also host your HTML5 applications.\n[…]\n```\n\n### Add media\n\nMedia should be added to `/static/images/`. Add a new directory if none of the available suits your needs.\n\nKeep all file names URL-friendly (lowercase, no special characters, and no empty spaces).\n\nTo use the images in your pages, just add the relative path, for example: `![image title](/images/\u003cdirectory name\u003e/\u003cfile name\u003e)`.\n\n\n## Redirects\n\nRedirects must be processed through aliases. Add aliases as an array, and make sure to remove `/docs` or `/guides` out of the URL. Check the following example:\n\n```yaml\n---\ntitle: Introduction to Cumulocity\nlayout: bundle\nweight: 10\naliases:\n  - /concepts/introduction-to-cumulocity/\n  - /concepts/introduction-to-cumulocity.html\n# this will redirect cumulocity.com/docs/concepts/introduction-to-cumulocity/\n# to cumulocity.com/docs/concepts/introduction\n---\n```\n\n## Deploying to cumulocity.com/guides\n\nCumulocity provides documentation for multiple releases. You must create a release branch for every public release, for example `release/r10.16.0`. When creating these branches follow the next steps:\n- Create the branch following the same pattern: `release/r[version number]`\n\n- Edit the `config.toml` file and append the version number to the base URL, for example: `baseURL = \"https://cumulocity.com/docs/r10.16.0\"`\n- Still on `config.toml` change the `guidesRedirect` to target the about page on the release, for example: `guidesRedirect = \"https://cumulocity.com/docs/r10.16.0/welcome/#introduction\"`\n- Add the file `properties.json` adding the name and the long name for the release version, for example: ```{\n  \"name\":\"r10.16.0\",\n  \"longname\": \"Release 10.16.0\"\n}```\n- Deploy using the Jenkins task `Deploy-c8y-docs-manual-release` and provide the release version\n- Deploy the `default` branch using the Jenkins task `Deploy-c8y-docs`  to regenerate the version dropdown links\n\n## Deploying to cumulocity.com/docs\n\nto be added\n\n## Automatic cherry-picking and labels\n\nAutomatic cherry-picking allows you to automatically cherry-pick your PRs to one or multiple release branches.\nIt works via the [backport-github-action](https://github.com/sqren/backport-github-action) which uses the [backport cli tool](https://github.com/sqren/backport) internally.\n\n### To enable automatic cherry-picking on a PR\n\nTo enable automatic cherry-picking on a PR, add the label `auto-backport` to it.\nOtherwise the responsible GitHub action is not going to be triggered.\n\nTo select the target branches you would like to cherry-pick your PR to, add labels of the following structure: `auto-backport-to-\u003ctargetBranch\u003e`.\nFor example: `auto-backport-to-release/r10.15.0` to cherry-pick it to the branch `release/r10.15.0` or `auto-backport-to-release/r10.14.0` for the branch `release/r10.14.0`.\n\nThe feature is triggered by either merging a PR with the `auto-backport` label or by adding the `auto-backport` label to an already closed and merged PR.\nIn the latter case, ensure that you first add the labels containing the target branches and then finally the `auto-backport` label.\nOtherwise the automation starts without any target branches.\n\n### Details\n\nThe PRs created by this GitHub action will have their heading prefixed with `[GRAFT] [\u003ctargetBranch\u003e]`. So, for example, for `release/r10.15.0` as the target branch and `[MTM-47706] fix publishing documentation` as the original PR heading, it results in  `[GRAFT] [release/r1015.0.0] [MTM-47706] fix publishing documentation` as the heading for the backport PR.\nIn case an assignee was set for the original PR, the cherry-picked PRs will also receive the same assignee. You must add reviewers manually after the cherry-picked PRs have been created.\n\nThe creation of cherry-picked PRs can take a few minutes.\nIf you are an assignee of the original PR, you receive an email notification once the cherry-picked PRs have been created.\nThe original PR is updated with a comment that contains links to the newly created cherry-picked PRs.\n\nIn case of a merge conflict while cherry-picking to a specific release branch, the branch will be skipped. Information on skipped branches is also included in the comment added to the original PR.\nIn that case you will have to take care of cherry-picking manually and resolve the conflicts.\nThis is not going to influence the other release branches as long as they do not have conflicts.\n\n\n---\n© Cumulocity GmbH  2025 + All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcumulocity-iot%2Fc8y-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcumulocity-iot%2Fc8y-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcumulocity-iot%2Fc8y-docs/lists"}