{"id":22326021,"url":"https://github.com/solarnetwork/solarnode-handbook","last_synced_at":"2026-03-19T22:25:34.855Z","repository":{"id":155730818,"uuid":"631826602","full_name":"SolarNetwork/solarnode-handbook","owner":"SolarNetwork","description":"Documentation for SolarNode.","archived":false,"fork":false,"pushed_at":"2025-03-14T02:52:09.000Z","size":12506,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-14T03:29:40.492Z","etag":null,"topics":["documentation"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SolarNetwork.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2023-04-24T06:29:24.000Z","updated_at":"2025-03-14T02:50:33.000Z","dependencies_parsed_at":"2024-01-23T21:37:56.740Z","dependency_job_id":"f98c2d71-edde-4e19-9b49-08eb6e5346ee","html_url":"https://github.com/SolarNetwork/solarnode-handbook","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/SolarNetwork%2Fsolarnode-handbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolarNetwork%2Fsolarnode-handbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolarNetwork%2Fsolarnode-handbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolarNetwork%2Fsolarnode-handbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SolarNetwork","download_url":"https://codeload.github.com/SolarNetwork/solarnode-handbook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245598320,"owners_count":20641884,"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":["documentation"],"created_at":"2024-12-04T02:15:05.136Z","updated_at":"2026-01-07T03:04:48.631Z","avatar_url":"https://github.com/SolarNetwork.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# SolarNode Handbook Source\n\nThis project is the source for the [SolarNode Handbook](https://solarnetwork.github.io/solarnode-handbook/).\n\n# Contributions welcome!\n\nWe welcome contributions to the SolarNode Handbook! Contributions can come in many forms and no\ncontribution is too small:\n\n * questions\n * spelling corrections\n * grammer suggestions\n * translations\n * clarifications\n * additional details\n * additional topics\n\nOpen an [issue](https://github.com/SolarNetwork/solarnode-handbook/issues) to start a discussion\non your contribution. You can fork this repository and open a pull request to submit your updates.\n\n# Writing documentation\n\nThe documentation for the Handbook is written using the [Markdown][md] syntax, with several handy\nextensions to help make the documentation look beautiful. The Markdown is rendered into HTML using\nthe [MkDocs][mkdocs] tool, using the [Material for MkDocs][mkdocs-material] theme. The Material for\nMkDocs site has good [documentation on the various Markdown\nextensions](https://squidfunk.github.io/mkdocs-material/reference/) that are supported.\n\n\u003e **Note** that a great way to learn the documentation syntax is to view the source for the\n\u003e page where you see a feature that you would also like to use.\n\n## Overview\n\nDocument pages are created in the `docs/` folder and must be named with a `.md` extension.\nSub-folders are supported, and form sections within the overall Handbook. For example, here is\na partial view of the `docs/` folder structure:\n\n```\ndocs/\n├── .pages\n├── developers/\n│   ├── .pages\n│   ├── index.md\n│   ├── osgi/\n│   ├── services/\n│   └── settings/\n├── index.md\n└── users/\n    ├── .pages\n    ├── configuration.md\n    ├── index.md\n    ├── logging.md\n    └── placeholders.md\n```\n\n## Navigation\n\nYou will notice there are `.pages` files within each folder in the `docs/` hierarchy. Those files\nare [YAML][yaml] configuration files that configure what navigation links should appear in the\nrendered Handbook. Their structure is quite simple, holding just a `title` property for the section\ntitle and  `nav` property with a list of page links. For example a `.pages` file might look like\nthis:\n\n```yaml\ntitle: Developer Guide\nnav:\n    - index.md\n    - osgi\n    - settings\n    - services\n```\n\nThis ends up generating the Handbook navigation, that looks like this:\n\n\u003cimg alt=\"Handbook navigation screen shot\" src=\"rsrc/nav-example.png\" width=\"208\"\u003e\n\nThe structure of each navigation item (the lines starting with `  - `) is\n\n```\ntitle: path\n```\n\nWhere `title` is an **optional** friendly name to show in the Handbook and `path` is a relative path\nto a folder or file. In the given example, there are four navigation links defined. The first link\nis to the main section content `index.md`, and the second has a label **Plugins** and a path to the\n`osgi` folder.\n\n### Page titles\n\nNavigation links can omit the `title` part of the link, in which case the title defined in the link\ndestination page itself will be used. A page defines its title with an initial level-1 Markdown header,\nlike this:\n\n```markdown\n# This Is My Page Title\n\nThis is the first paragraph of the page.\n\n## This Is A Level-2 Markdown Header\n\nThis is the first paragraph of the first sub-heading.\n```\n\nIn that example, the page title is **This Is My Page Title**.\n\n### Sections\n\nThe top-level `developers/` and `users/` folders form the top-level **Developers** and **Users** sections\nwithin the Handbook. The `index.md` file within those folders holds the content for those sections.\n\n### Sub-sections\n\nThe `osgi/`, `services/`, and `settings/` folders within the `developers/` folder form sub-sections\nwithin the top-level **Developers** section. Sub-sections also start with an `index.md` file for\ntheir content.\n\n### Omitting a `.pages` file\n\nAny section can omit its `.pages` file, in which case all the files within that section will be\nautomatically included as navigation links, sorted by their titles.\n\n## Links\n\nLinks can be added to both internal Handbook pages and external resources. The basic structure\nof a Markdown link looks like this:\n\n```markdown\n[label](url)\n```\n\nThe `label` is the text to display and `url` is the URL to link to.\n\n### Internal links\n\nLinks to internal pages, and specific headers, are possible by using a **relative** path to\nthe page file. For example if the `developers/services/foo.md` page needed a link to the\n`users/bar.md` page, the link would look like:\n\n```markdown\n[link to bar](../../users/bar.md)\n```\n\nIf `bar.md` had a header you wanted to link directly to, you can add a `#header` to the link URL\nwhere `header` is a lower-cased, non-standard-character-to-dash form of the header. For example\nif `bar.md` had a header like this:\n\n```markdown\n## Important information\n```\n\nthen a link to that header would be:\n\n```markdown\n[link to bar header](../../users/bar.md#important-information)\n```\n\n\n# Build requirements\n\n * [MkDocs][mkdocs]\n * [mkdocs-awesome-pages-plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin)\n * [mkdocs-enumerate-headings-plugin](https://github.com/timvink/mkdocs-enumerate-headings-plugin)\n * [mkdocs-material][mkdocs-material]\n * [mkdocs-open-in-new-tab](https://github.com/JakubAndrysek/mkdocs-open-in-new-tab)\n\n\n## macOS\n\nOn macOS, you can install MkDocs with Homebrew, then use `pip3` to install the\nPython packages:\n\n```sh\nbrew install mkdocs\npip3 install mkdocs-awesome-pages-plugin mkdocs-enumerate-headings-plugin mkdocs-material mkdocs-open-in-new-tab\n```\n\n# Building\n\nTo build and view the handbook on your own machine, run `mkdocs serve`. You can then view\nthe handbook at http://localhost:8000/solarnode-handbook/.\n\nTo deploy the changes, run `mkdocs gh-deploy`.\n\n[md]: https://en.wikipedia.org/wiki/Markdown\n[mkdocs]: https://github.com/mkdocs/mkdocs/\n[mkdocs-material]: https://github.com/squidfunk/mkdocs-material\n[yaml]: https://en.wikipedia.org/wiki/YAML\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolarnetwork%2Fsolarnode-handbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolarnetwork%2Fsolarnode-handbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolarnetwork%2Fsolarnode-handbook/lists"}