{"id":19270369,"url":"https://github.com/netdata/learn","last_synced_at":"2025-08-08T01:10:33.642Z","repository":{"id":36963935,"uuid":"243627634","full_name":"netdata/learn","owner":"netdata","description":"A public site to learn about Netdata built on Docusaurus 2","archived":false,"fork":false,"pushed_at":"2025-04-17T10:44:19.000Z","size":25833,"stargazers_count":37,"open_issues_count":2,"forks_count":23,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-18T01:28:21.943Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/netdata.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":null,"security":"docs/security-and-privacy-design/netdata-agent-security-and-privacy-design.mdx","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-27T22:13:51.000Z","updated_at":"2025-04-15T06:48:24.000Z","dependencies_parsed_at":"2025-04-17T11:59:04.305Z","dependency_job_id":null,"html_url":"https://github.com/netdata/learn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdata%2Flearn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdata%2Flearn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdata%2Flearn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdata%2Flearn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netdata","download_url":"https://codeload.github.com/netdata/learn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250128498,"owners_count":21379523,"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-11-09T20:24:34.135Z","updated_at":"2025-08-08T01:10:33.624Z","avatar_url":"https://github.com/netdata.png","language":"JavaScript","readme":"# Netdata Learn\n\nThis repository hosts the code for Netdata's documentation site, **Netdata Learn** built on [Docusaurus](https://docusaurus.io/).\n\n\u003e **Important**\n\u003e\n\u003e This repo is a **mirror**! Means any changes made here on the `docs/` directory will be overwritten from the [`netdata/netdata`](https://github.com/netdata/netdata)\n\nThe site is then deployed automatically to Netlify from the latest ingested commit of the [`netdata/netdata`](https://github.com/netdata/netdata) master branch, which we also use to maintain certain redirects.\n\n## Netlify status\n\nmaster    : [![Netlify Status](https://api.netlify.com/api/v1/badges/bafd033d-602b-4635-94f4-17c0b1235480/deploy-status)](https://app.netlify.com/sites/netdata-docusaurus/deploys) \u003c/br\u003e\nstaging  : [![Netlify Status](https://api.netlify.com/api/v1/badges/bafd033d-602b-4635-94f4-17c0b1235480/deploy-status?branch=staging)](https://app.netlify.com/sites/netdata-docusaurus/deploy-status?branch=staging) \u003c/br\u003e\nstaging1  : [![Netlify Status](https://api.netlify.com/api/v1/badges/bafd033d-602b-4635-94f4-17c0b1235480/deploy-status?branch=staging1)](https://app.netlify.com/sites/netdata-docusaurus/deploy-status?branch=staging1) \u003c/br\u003e\n\n## Contributing to Netdata Learn\n\nMost of the files in the `/docs` folder are \"mirrors\" of their original files found in the [ingested repositories](#ingested-repositories).\n\nThe files in the `/docs` folder of repository should not be edited.\n\nThe [documentation contribution guidelines](https://github.com/netdata/netdata/blob/master/docs/guidelines.md) explain this architecture a bit further and go through some of the methods for making or suggesting edits.\n\nPlease also look at the [style guide](https://github.com/netdata/netdata/blob/master/docs/developer-and-contributor-corner/style-guide.md). We offer friendly advice on producing quality documentation, hoping that it will help you contribute.\n\n## Local Deploy of Learn\n\n1. Clone this repository\n\n    ```bash\n    git clone https://github.com/netdata/learn.git\n    cd learn\n    ```\n\n2. `yarn` version `14.16` or higher should be installed on the system, usually with `npm install yarn` (you can also use the `--global` tag)\n3. `node.js`, version `12 - 16` should also be installed on the system, `nvm` works best for this, so you can hot-swap node.js versions.\n4. Install dependencies.\n\n    ```bash\n    yarn install\n    ```\n\n5. To start the frontend end of Learn, running at port `3000`, use:\n\n```bash\nyarn start\n```\n\nThis command starts a local development server and opens up a browser window. Markdown changes are reflected live without having to restart the server (removing/adding files will need a re-run of the command). If you want to suppress warnings you can run `yarn -s start`.\n\n## Ingest and process documentation files\n\nAs explained in the [contributing to Netdata Learn](#contributing-to-netdata-learn) section above,\nall of the files in the `/docs` folder are mirrors of their original versions located in Netdata's repositories.\n\n### Manual ingest via local environment\n\nYou can run the ingest script manually in a local development environment. Most of the time you will make changes in any repo of the [repos](#ingested-repositories) (or your forks).\nTo do that you need to setup your local environment for the ingest process to work.\nThe ingest script is a python script and has its dependencies (separate from the docusaurus framework).\n\n#### Prerequisites\n\n- Python v3.9+\n\n#### Steps\n\n1. Navigate under your `netdata/learn` local clone.\n\n2. (Optional) Create a local test branch otherwise work on the `master` branch.\n\n3. Create a python virtual environment.\n\n    ```bash\n    python -m venv myenv\n    ```\n\n    The name `myenv` is included in the `.gitignore` file of this repo.\n\n4. Activate your environment.\n\n    ```bash\n    source myenv/bin/activate\n    ```\n\n5. Install the required packages, via pip\n\n    ```bash\n    pip install -r .learn_environment/ingest-requirements.txt\n    ```\n\n6. The organization of the files is handled by the [`map.tsv` file](https://docs.google.com/spreadsheets/d/1DhwL1yr7-sY6f8vfyHsKlPqxhu4_zUHXYiBrllglFfc/edit?usp=sharing), that contains metadata for every file. That file should only be edited by members of the Netdata team.\n\n7. Once you edit the file from Google Sheets, you download the **second** sheet and replace `map.tsv` in your local repo.\n\n8. Run the ingest process to fetch the documents you are working on from one or multiple repos.\n\n    ```bash\n    python ingest/ingest.py --repos \u003cowner\u003e/\u003crepo\u003e:\u003cbranch\u003e\n    ```\n\n    for example, let's assume that you made some changes in the markdown files of `netdata/netdata` repo (branch: patch1)\n    and on your own fork `user1/go.d.plugin` repo (branch: user1-patch).\n\n    ```bash\n    python ingest/ingest.py --repos netdata/netdata:patch1 user1/go.d.plugin:user1-patch\n    ```\n\n    If you don't use `--repos` the ingest will run on the master branches of netdata's repos.\n\n9. You then need to run `ingest/create_grid_integration_pages.py` to generate the dynamic integration pages.\n  \n10. Build a local website  \n\n    ```bash\n    yarn start\n    ```\n\n    You can also build the project instead of running by:\n\n    ```bash\n    yarn build\n    ```\n\n    and then:\n\n    ```bash\n    npm run serve\n    ```\n\n### Ingested repositories\n\nAt the moment documentation is ingested from the following repos:\n\n- netdata/netdata\n- netdata/.github\n- netdata/agent-service-discovery\n- netdata/netdata-grafana-datasource-plugin\n- netdata/helmchart\n\nDocumentation arrives in this repository via the [`ingest.py`](/ingest/ingest.py) script. This script clones the repos and processes all of Netdata's documentation, including changing file paths and overwriting links between documents, then places the files in the `/docs` folder.\n\n### Automated ingest via GitHub Actions\n\nThis repo uses a GitHub Action called [`ingest.yml`](.github/workflows/ingest.yml) to run the `ingest/ingest.py` process.\n\nThis action runs at 14:00 UTC every day.\n\nIf there are changes to any documentation file, the GitHub Action creates a PR that is then reviewed by a member of the Netdata team.\n\nThe action can be configured to automatically assign one or more reviewers.\nTo enable automatic assignments, uncomment the `# reviewers:` line at the end of [`ingest.yml`](.github/ingest.yml) and add the appropriate GitHub username(s)either space or comma-separated.\n\n## Update news on the Learn homepage\n\nThere are two parts to the news section on the Learn homepage: the _timeline_ and the _latest release_.\n\n### Timeline\n\nThe timeline section on the Learn homepage should be updated whenever the team publishes new docs/guides or when an\nexisting doc/guide receives a major overhaul/improvement.\n\n1. Open the `/src/data/News.js` file.\n2. Find the `News` array near the top of the page.\n3. Duplicate an existing item and replace the `title`, `href`, `date`, `type`, and `description` fields.\n     1. `title` can be pulled directly from .md file.\n     2. `href` field is the full path, including the root /, to that document.\n     3. `date` is the date that doc was published/updated.\n     4. `type` is one of the following: Doc, Guide, Video\n     5. `description` can be pulled directly from .md file. It must be surrounded by the \u003c\u003e … \u003c/\u003e tags to React-ify it and escape any troublesome characters.\n4. The end result should look something like this:\n\n     ```js\n     const updates = [\n       {\n         title: \u003c\u003eMonitor any process in real-time with Netdata\u003c/\u003e,\n         href: '/guides/monitor/process',\n         date: 'December 8, 2020',\n         type: 'Guide',\n         description: (\n           \u003c\u003e\n             Tap into Netdata's powerful collectors, with per-second utilization metrics for every process, to troubleshoot faster and make data-informed decisions.\n           \u003c/\u003e\n         ),\n       },\n       ...\n     ]\n     ```\n\n5. If you added one news item, delete the oldest item from the list. Try to maintain only 6 items in the list at any one time.\n6. Save the file, commit, and push your code. Create a new PR, check the deploy preview, get a review, and merge it.\n\n### Latest release\n\nUpdate the latest release section when there is a new release of Netdata, like `1.31.0` → `1.32.0`.\n\n1. Open the /src/data/News.js file.\n2. Find the `ReleaseVersion` and `ReleaseDate` variables, and the `ReleaseNotes` array.\n3. Update the version and date.\n4. Update the major features in `ReleaseNotes`, which are then converted into the list.\n5. The end result should look something like this:\n\n      ```js\n      export const ReleaseVersion = '1.31.0'\n\n      export const ReleaseDate = 'May 19, 2021'\n\n      export const ReleaseNotes = [\n        'Re-packaged and redesigned dashboard',\n        'eBPF expands into the directory cache',\n        'Machine learning-powered collectors',\n        'An improved Netdata learning experience',\n      ]\n      ```\n\n6. Save the file, commit, and push your code. Create a new PR, check the deploy preview, merge it.\n\n## Edit CSS\n\nGlobal CSS rules are stored in `/src/css/custom.css` file.\n\nThe various pages and components that make up Learn also come with extra CSS using [Tailwind](https://tailwindcss.com/),\nwhich uses utility classes to create styling. You can find these utility classes throughout the components and pages.\n\nFor example, the following utility classes style the hero text on the Learn homepage.\n\n```css\n\u003cdiv className=\"z-10 relative w-full md:w-3/4 lg:w-1/2\"\u003e\n  \u003ch1 className=\"text-2xl lg:text-5xl text-text font-semibold mb-6 dark:text-gray-50\"\u003e{siteConfig.title}\u003c/h1\u003e\n  \u003cp className=\"prose text-lg lg:text-xl text-text dark:text-gray-50\"\u003e{siteConfig.tagline}\u003c/p\u003e\n\u003c/div\u003e\n```\n\n## Build\n\n```console\nyarn build\n```\n\nThis command generates static content into the `build` directory and can be served using any static contents hosting service.\n\n### Custom (swizzled) Docusaurus components\n\nEvery `.js` file in the `/src/theme` folder is a component that has been customized from the defaults supplied by Docusaurus.\nThis process is called [swizzling](https://docusaurus.io/docs/using-themes#swizzling-theme-components).\n\nIf you update Docusaurus, these swizzled components aren't updated. This could create some breakage if there are major changes to the default versions of these components in the Docusaurus core.\nThe only solution is to merge the existing customizations with the new version of the file or remove the customizations altogether.\n\nTo merge:\n\n1. Make a copy of the component (`xyz.js`) in the `/src/theme` folder and save it outside the repo.\n2. Delete the file/folder for that component.\n3. Run `yarn run swizzle @docusaurus/theme-classic NAME`, replacing `NAME` with the name of the component, like `DocItem` or `Seo`. You may also have to add a `-- --danger` to the end: `yarn run swizzle @docusaurus/theme-classic NAME -- --danger`.\n4. Open the newly-created `.js` file in the `/src/theme` folder.\n5. Add the customization (the code between `BEGIN EDIT`/`END EDIT`) comments, back into the file in the appropriate place.\n6. Start Docusaurus with `yarn start` and test.\n\n## Deployment\n\nDeployment is handled automatically through Netlify. Each new commit to the `master` branch deploys the latest version of Netdata Learn.\n\nIf there are questions about deployment, please create an issue.\n\n### Redirects\n\nIf a document is moved from one location to another, the ingest script is responsible for generating relative redirects.\n\nThere is also a `static.toml` file, containing more complex, static redirects.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetdata%2Flearn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetdata%2Flearn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetdata%2Flearn/lists"}