|
1 | 1 | # Hoverkraft Documentation Portal |
2 | 2 |
|
3 | | -Public documentation portal for Hoverkraft open-source projects (aka openkraft). |
| 3 | +Public documentation hub for Hoverkraft (aka openkraft) projects and methodologies. |
4 | 4 |
|
5 | | -This repository contains the source code for the Hoverkraft documentation site built with [Docusaurus](https://docusaurus.io/). |
| 5 | +--- |
6 | 6 |
|
7 | | -## 🚀 Quick Start |
| 7 | +## Overview |
8 | 8 |
|
9 | | -### Prerequisites |
| 9 | +The portal aggregates technical guides, project overviews, and methodology notes from the Hoverkraft ecosystem. The CI pipeline ingests metadata (topics, readmes, release notes) from public repositories and renders them as curated documentation pages. |
10 | 10 |
|
11 | | -- Node.js 20.0 or higher |
12 | | -- npm |
| 11 | +## Documentation Areas |
13 | 12 |
|
14 | | -### Installation |
| 13 | +- **Methodology** — Delivery practices, CI/CD playbooks, and platform standards (`application/docs/methodology/`) |
| 14 | +- **Projects** — Directory of open-source projects managed by Hoverkraft (`application/docs/projects.md`) |
| 15 | +- **Internal notes** — Keep internal or implementation-specific documentation concise in this root readme; `application/docs/` is limited to public-facing content. |
15 | 16 |
|
16 | | -```bash |
17 | | -make prepare |
18 | | -``` |
19 | | - |
20 | | -### Development |
| 17 | +## Site Structure |
21 | 18 |
|
22 | | -Start the development server: |
| 19 | +The site is built with [Docusaurus](https://docusaurus.io/) and published as a static site from the `application/` workspace. |
23 | 20 |
|
24 | | -```bash |
25 | | -make start |
| 21 | +``` |
| 22 | +application/ |
| 23 | +├── docs/ # Markdown sources rendered by Docusaurus |
| 24 | +├── src/ # React components, pages, and styling modules |
| 25 | +│ ├── components/ # Shared UI components |
| 26 | +│ └── pages/ # Custom pages & route overrides |
| 27 | +├── static/ # Static assets served verbatim (images, icons) |
| 28 | +├── docusaurus.config.ts # Global Docusaurus configuration |
| 29 | +├── sidebars.ts # Sidebar definitions per documentation section |
| 30 | +└── build/ # Generated static site output (do not edit) |
26 | 31 | ``` |
27 | 32 |
|
28 | | -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. |
| 33 | +Generated files in `application/build/` are artifacts only—never commit manual edits to that directory. |
29 | 34 |
|
30 | | -### Build |
| 35 | +`application/docs/` is published publicly. Avoid adding internal runbooks or sensitive implementation notes there—document those at the repository root instead. |
31 | 36 |
|
32 | | -```bash |
33 | | -make build |
34 | | -``` |
| 37 | +## Content Pipeline |
35 | 38 |
|
36 | | -This command generates static content into the `build` directory and can be served using any static contents hosting service. |
| 39 | +The documentation build pulls repository information through scheduled jobs and manual syncs: |
37 | 40 |
|
38 | | -## 📁 Project Structure |
| 41 | +- Repository topics and descriptions feed project listings. |
| 42 | +- Published readmes and docs are mirrored into portal sections. |
| 43 | +- Social preview images are reused as hero assets where available. |
| 44 | +- Metadata updates require a rebuild (`make build`) to appear in the published site. |
39 | 45 |
|
40 | | -``` |
41 | | -├──application/ |
42 | | - ├── docs/ # Documentation pages |
43 | | - ├── src/ # Source files (React components, pages, etc.) |
44 | | - │ ├── components/ # React components |
45 | | - │ ├── css/ # CSS files |
46 | | - │ └── pages/ # Additional pages |
47 | | - ├── static/ # Static assets |
48 | | - ├── docusaurus.config.ts # Docusaurus configuration |
49 | | - └── sidebars.ts # Sidebar configuration |
50 | | -``` |
| 46 | +## Development Workflow |
51 | 47 |
|
52 | | -## 🛠️ Customization |
| 48 | +```bash |
| 49 | +make prepare # Install npm dependencies in application/ |
| 50 | +make start # Launch the Docusaurus dev server with live reload |
| 51 | +make lint # Run linters (Markdown, CSS, JS/TS, config files) |
| 52 | +make lint-fix # Auto-fix supported lint issues via repository formatter |
| 53 | +make build # Produce static site in application/build |
| 54 | +make ci # CI helper: prepare + lint-fix + build |
| 55 | +``` |
53 | 56 |
|
54 | | -This portal is designed to dynamically build content from Hoverkraft's public repositories. The CI workflow will scan repositories and build the portal using: |
| 57 | +- The dev server runs at `http://localhost:3000` and hot-reloads on content or component changes. |
| 58 | +- To lint or format a subset of files, pass a glob to `make lint path/to/file.md`. |
| 59 | +- Check in only Markdown, TypeScript, and asset changes—generated output is rebuilt by CI. |
55 | 60 |
|
56 | | -- Repository topics and descriptions |
57 | | -- Social preview images |
58 | | -- Readme files and documentation |
59 | | -- Other useful metadata |
| 61 | +## Contributing |
60 | 62 |
|
61 | | -## 📝 Contributing |
| 63 | +1. Fork the repository. |
| 64 | +2. Create a feature branch (`git checkout -b feature/<feature-name>`). |
| 65 | +3. Run the development workflow commands relevant to your change (`make start`, `make lint`, etc.). |
| 66 | +4. Commit using conventional messages when possible (`feat:`, `fix:`, `docs:`). |
| 67 | +5. Open a Pull Request and ensure CI passes. |
62 | 68 |
|
63 | | -1. Fork the repository |
64 | | -2. Create your feature branch (`git checkout -b feature/amazing-feature`) |
65 | | -3. Commit your changes (`git commit -m 'Add some amazing feature'`) |
66 | | -4. Push to the branch (`git push origin feature/amazing-feature`) |
67 | | -5. Open a Pull Request |
| 69 | +Refer to `CONTRIBUTING.md` for detailed development standards and release expectations. |
68 | 70 |
|
69 | | -## 📄 License |
| 71 | +## License |
70 | 72 |
|
71 | | -This project is part of the Hoverkraft open-source ecosystem. |
| 73 | +This project is part of the Hoverkraft open-source ecosystem and is distributed under the MIT License. |
0 commit comments