{"id":31637555,"url":"https://github.com/metal-stack/website","last_synced_at":"2025-10-07T01:15:22.001Z","repository":{"id":312262148,"uuid":"982876910","full_name":"metal-stack/website","owner":"metal-stack","description":"Website of metal-stack.io","archived":false,"fork":false,"pushed_at":"2025-10-02T13:25:19.000Z","size":24644,"stargazers_count":0,"open_issues_count":28,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-02T13:39:07.350Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://metal-stack.io/","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metal-stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/01-Proposals/MEP1/Distributed-API-Working.png","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","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":"2025-05-13T14:35:15.000Z","updated_at":"2025-10-02T11:56:28.000Z","dependencies_parsed_at":"2025-10-02T13:38:11.759Z","dependency_job_id":null,"html_url":"https://github.com/metal-stack/website","commit_stats":null,"previous_names":["metal-stack/website"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/metal-stack/website","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fwebsite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fwebsite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fwebsite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fwebsite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metal-stack","download_url":"https://codeload.github.com/metal-stack/website/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fwebsite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278705723,"owners_count":26031602,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-10-07T01:15:19.816Z","updated_at":"2025-10-07T01:15:21.988Z","avatar_url":"https://github.com/metal-stack.png","language":"MDX","readme":"# website\n\n[![Netlify Status](https://api.netlify.com/api/v1/badges/927c840e-43dc-4721-9d49-aac06f52c33f/deploy-status)](https://app.netlify.com/projects/metal-stack-io/deploys)\n\nThis repository contains the website including the documentation of [metal-stack.io](https://metal-stack.io).\n\nThe used framework to generate docs is [docusaurus](https://docusaurus.io).\n\n## Structure\n\n```plain\n├── blog                    # blogs folder structured by year\n│   ├── 2019\n│   ├── 2021\n│   ├── 2022\n│   ├── 2023\n│   ├── 2024\n│   └── 2025\n├── docs                    # docs folder split by different scopes\n│   ├── contributing        # guidelines for contributors\n│   ├── docs                # documentation pages\n│   ├── references          # auto-generated references of components and apis\n├── scripts                 # custom scripts (e.g: resolving component documentation)\n├── src                     # custom routes and react\n│   ├── components\n│   ├── css\n│   ├── pages\n│   └── plugins\n├── versioned_docs          # versioned docs (full copy of docs-folder)\n│   ├── version-v0.21.4\n│   └── version-v0.21.5\n├── versioned_sidebars      # versioned sidebars\n├── docusaurus.config.ts    # main docusaurus config\n├── sidebars.ts             # handle sidebar navigation structure\n└── versions.json           # list of versions\n```\n\n### How to Organize the Docs?\n\n- Prioritize the `concept` section. If this is about a MEP, you likely already have the contents for this.\n- Use the `general` section to distribute users to their sections or to the deeper concept.\n- user, operator or developer specific sections would be nice, but are optional.\n\n#### Example\n\n- Roles and Permissions\n  - Concept: explains all roles, permissions and sessions\n  - For operators: OIDC, creation in CI, ... How to / Explanation\n  - For users: how to guide to create tokens and edit permissions\n  - General: base concept, links to How to guides and deeper Concept\n  - CISO / Compliance: minimal need to know Principle Explanation / Concept\n\n## Backwards-Compatibility\n\nIn order to not break links of posts, blog articles and shared documents we want to provide full backwards-compatibility.\nThis means we need to ensure existing links still work with the new documentation.\n\nThe file /static/_redirects contains a list of all paths of the old docs-sites. The file is formatted to create server-side-redirects on netlify, following the documentation here: https://docs.netlify.com/routing/redirects/\n\n## Docs\n\nIn order to add new docs you need to be aware of 2 cases:\n\n### Root-Dir Doc\n\nIf you want to have your new document in the root-folder of the scope just add it with the following format:\n\n```yaml\n---\nslug: /your-doc-url\ntitle: Title of document\nposition: \u003cPosition in sidebar as number\u003e\n---\n\n\u003cHERE YOUR DOCS\u003e\n```\n\n### Sub-Dir Doc\n\nIf you want to have a new document in the sub-folder of the scope just add it the same as before, but make sure you have a `_category_.json`.\nThis file is used to generate the sidebar.\n\n```json\n{\n  \"position\": 2,\n  \"label\": \"Overview\"\n}\n```\n\n## Embedding drawio images\n\n\u003e ⚠️ referenced `.drawio.svg` images throw **warnings** because of unsupported file-types. We save `.drawio` files separately and export them as `svg`. Issue is also known in [docusaurus](https://github.com/facebook/docusaurus/issues/9715)\n\nSome svgs still can have problems e.g:\n\n- `drawio.svg` files pulled by references\n- too large svg\n\nFor this we have a pre-commit hook, which optimizes them with [svgo](https://github.com/svg/svgo)\n\n## Blog\n\nIn order to add a blog-post follow this template. If a new author is referenced you have to add the author to the `authors.yaml`.\n\n```yaml\n---\ntitle: Your Title\nwatermark: \"Blog\"\ndate: 2025-02-03T10:00:00+02:00\ndescription: short description of the post\nauthors: [gerrit91]\ntype: \"blog\"\ncategories:\n  - \"Conferences\"\ntags:\n  - 'News'\n  - 'Conferences'\n---\n\n\u003cSOME PREVIEW TEXT FOR BLOG LIST VIEW\u003e\n\n\u003c!-- truncate --\u003e\n\n\u003cYOUR ARTICLE\u003e\n```\n\n## Setup \u0026 Build\n\nRequires Bun as .js runtime.\n\nRun the following command to install dependencies:\n\n```bash\nbun install\n```\n\nTo generate a local preview use:\n\n```bash\nbun run start\n```\n\nTo update the dependencies for the Reference pages:\n\n```bash\nbun run fetch-readmes\n```\n\n## Component References\n\nEnsure first, that all files in the docs folder are updated and ready to freeze. Also execute `bun run fetch-readmes` to update files from components and apis with the release-vector file from the main branch.\nIt is also possible to use `bun run fetch-readmes v0.20.8` to use the release-vector file with a specific tag (i.E. v0.20.8).\nAll components are referenced in the `/scripts/components.json` file. Use this minimal template to add a new component:\n\n```jsonc\n{\n        \"name\": \"metalctl\", // name of the component, will appear in the navigation\n        \"releasePath\": \"binaries.metal-stack.metalctl.version\", // json-path of the version or tag in the release-vector\n        \"branch\": \"main\", // branch name. Some old repositories use 'master'\n        \"repo\": \"metal-stack/metalctl\", // component repository,\n        \"tag\": \"v0.18.1\", // latest release tag of the component repository\n        \"position\": 1, // use this property to sort the navigation subdirectories\n        \"withDocs\": true // set to true to retrieve further .md files from a /docs folder. With false, only the README.md will be retrieved.\n}\n```\n\nThe `tag` property will be updated automatically from the release-vector file.\n\n## Document Versioning\n\nYou create a new version with:\n\n```bash\nbun run docusaurus docs:version v0.21.6\n```\n\nNow, the new version will be create and the latest files will be copied to the \"`versioned`\" folders.\n\nThis, however, is usually done by the metal-robot through an automatically generated pull request.\n\n## Release Notes\n\nThe release notes can be synced from GitHub with the GitHub API. Therefore, ensure that a valid access token is created and set on the GitHub Runner or local machine with the name `GITHUB_TOKEN`.\n\nTo run the synchronization, run the following command:\n\n```bash\nbun run create-release-notes\n```\nIf you run this before the build step, also the release notes get indexed.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fwebsite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetal-stack%2Fwebsite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fwebsite/lists"}