--- title: About Docs slug: one/resources/about-docs docTags: createdAt: 2026-06-10T18:09:43.572Z --- The Developer Portal (also called the wiki or the Docs) is the main documentation for FlipperΒ One sub-projects. We update it as we work on Flipper One, so some pages may change frequently. This page explains how the Docs are organized, how pages are stored and published, and how you can contribute. ![About Docs](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/c74jZfWJ7jVKLHm2R2KQq_about-docs-main-image.jpg) The Docs sub-project covers all documentation for Flipper One: this wiki, technical specs, datasheets, guides, and contribution instructions. Like all other Flipper One sub-projects, it is open for community contribution. The Docs sub-project consists of: - βœ… [Task tracker](https://github.com/orgs/flipperdevices/projects/10) - πŸ“ [Source Markdown files on GitHub](https://github.com/flipperdevices/flipperone-docs) - πŸ“Š [Diagrams on Miro](https://miro.com/app/board/uXjVJ6y839o=/?moveToWidget=3458764666602002588\&cot=10) - 🎨 [Illustrations on Figma](https://www.figma.com/design/HcwlmmIJlW4LoiQu4RtwwH/Flipper-One-%E2%80%94-Docs?node-id=71-3\&t=56y5oAygKLBg3nGe-1) We’d love your feedback and help so look for tasks tagged **help wanted** in the task tracker, or contribute directly to the Docs GitHub repository via pull requests. ![Docs sub-project structure](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/Qj2s_qcR6PuQPU09M1bib_docs-sub-project-structure.jpg) *** ## How the Developer Portal works The Flipper One Developer Portal is hosted on [Archbee](https://archbee.com), but all source files live in the [GitHub repository](https://github.com/flipperdevices/flipperone-docs) thanks to Archbee's GitHub integration. Diagrams, screenshots, and illustrations are created in Miro and Figma, then exported to the repository alongside the Markdown. ![How the Developer Portal works](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/UFfEOltqY-uWbOWOknlNE_how-docs-work.jpg "How the Developer Portal works") The repository has one long-lived branch: - `public-release` production branch connected to Archbee. All pull requests from contributors target `public-release`. Once merged, Archbee rebuilds and publishes the live docs at [docs.flipper.net/one](https://docs.flipper.net/one). *** ## βœ… Task tracker All Docs sub-project tasks are tracked in the GitHub project [Flipper One β€” Docs](https://github.com/orgs/flipperdevices/projects/10). There, you can see what the team is working on and find open tasks where the community can help. ![Docs board explainer](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/Wx_eNFLs3-IzoFKMCnDQE_docs-board-explainer.png "How the Docs task tracker is organized") Tasks labeled **help wanted** are open for contribution. You’re welcome to join discussions or submit changes, but please read the [Contribution guide](docId:5qbNeaaFeDvyK2XIS_-Zv) first. *** ## πŸ“ GitHub repository structure The [flipperone-docs](https://github.com/flipperdevices/flipperone-docs) repository contains the source files for the entire Developer Portal: ```none flipperone-docs/ β”œβ”€β”€ .github/ β”‚ └── workflows/ β”‚ β”œβ”€β”€ update-open-tasks.yml # Regenerates Open-tasks.md β”‚ └── validate.yml # Validates docs structure and links on PRs β”œβ”€β”€ archbee.json # Sidebar hierarchy + Archbee integration settings β”œβ”€β”€ README.md # Repository overview β”œβ”€β”€ tools/ β”‚ └── generate_open_tasks.py # Generates Open-tasks.md from GitHub issues └── docs/ β”œβ”€β”€ Welcome.md # Main page at docs.flipper.net/one β”œβ”€β”€ How-to-join.md β”œβ”€β”€ Open-tasks.md # Auto-generated β€” do not edit manually β”œβ”€β”€ general/ # Tech specs, controls, and features β”œβ”€β”€ hardware/ # πŸ”Œ Hardware sub-project β”œβ”€β”€ mechanics/ # βš™οΈ Mechanics sub-project β”œβ”€β”€ cpu-software/ # 🐧 Linux (CPU Software) sub-project β”œβ”€β”€ mcu-firmware/ # πŸ•ΉοΈ MCU Firmware sub-project β”œβ”€β”€ user-interface/ # 🎨 User Interface sub-project β”œβ”€β”€ testing/ # πŸ§ͺ Testing sub-project β”œβ”€β”€ resources/ β”‚ β”œβ”€β”€ docs/ # Docs sub-project β”‚ └── rockchip/ # Rockchip RK3576 reference └── files/ β”œβ”€β”€ pics/ # Images and other assets └── icons/ # OS / brand icons used in docs ``` *** ### Markdown and Archbee syntax All pages in the Developer Portal are written in **Markdown** (`.md`). On top of standard Markdown, Archbee adds a set of components for callouts, tabs, workflow blocks, embedded media, and more. For the full list of supported syntax with live examples, see the [Markup reference](docId\:L8V_N7C30UTmEEIh2vl-7) page. It covers: - Headings, lists, links, and tables - Callouts - Images and videos - Code blocks and tabbed code - Workflow steps and other Archbee components :::hint{type="info"} Always check the [Markup reference](docId\:L8V_N7C30UTmEEIh2vl-7) page before writing or editing as some Markdown features behave differently in Archbee, and component syntax can be easy to mistype. ::: *** ### Writing style Syntax is only half the picture. The Developer Portal also follows a shared [Style guide](docId\:C55XJ4-oFpj-7aKREaXCI) so every page keeps a consistent tone, voice, and formatting. It covers: - Tone of voice - Language, spelling, and terminology - Headings, links, lists, and emphasis - Numbers, units, punctuation, and typography :::hint{type="info"} Skim the [Style guide](docId\:C55XJ4-oFpj-7aKREaXCI) before opening a pull request. Matching the existing tone and formatting helps your contribution get merged faster. ::: *** ### Images and other assets All images, diagrams, and screenshots live in a single folder: `docs/files/pics/`. Keeping everything in one place makes it easier to find, reuse, and clean up unused files. To use an image in a page, reference it from your Markdown using a relative path: ```markdown ![Caption text](/files/pics/your-image.png) ``` For richer Archbee image syntax (positioning, captions, sizing), see the [Markup reference](docId\:L8V_N7C30UTmEEIh2vl-7) page. β€Ž Naming and size guidelines: - Use descriptive, lowercase filenames with hyphens (for example, `gpio-pinout.png`, not `IMG_0042.PNG`). - Compress large screenshots before committing. Keep individual files under a few MB where possible. - Prefer `.png` for screenshots and diagrams, `.jpg` for photos. *** ### How archbee.json works `archbee.json` lives at the repository root and defines the Developer Portal’s left sidebar (table of contents): sections, page names, file paths, and nesting levels. When adding a new page, always update [archbee.json](https://github.com/flipperdevices/flipperone-docs/blob/public-release/archbee.json) to include it. Without this, the page won’t appear in the sidebar, and readers won’t be able to find it. ### Syntax The sidebar tree lives in `structure.docsTree` β€” an array of entries that are either pages or category groups. For example: ```json { "root": "./docs", "structure": { "readme": "Welcome.md", "assets": "files", "docsTree": [ { "categoryName": "Welcome", "isCategory": false, "path": "Welcome.md", "children": [] }, { "categoryName": "πŸ”Œ Hardware", "isCategory": true, "children": [ { "categoryName": "About Hardware", "isCategory": false, "path": "hardware/About-Hardware.md", "children": [] }, { "categoryName": "GPIO port", "isCategory": false, "path": "hardware/GPIO-port.md", "children": [ { "categoryName": "GPIO modules", "isCategory": false, "path": "hardware/GPIO-Modules.md", "children": [] } ] } ] } ] } } ``` β€Ž ### Rules - Pages are entries with a path to an `.md` file inside `docs/`. - Categories are group headers that visually separate sections (for example, πŸ”Œ Hardware). They have no path, only nested entries. - Any page can also have nested sub-pages under it. - The sidebar label comes from `categoryName`. Emojis render as-is and are purely cosmetic. ### Page metadata Every page starts with a YAML frontmatter block at the top of the `.md` file. Archbee reads two fields from it: - `title:` the page title shown as the H1 on the live site and as the page name in the sidebar. Do not add a `# Title` line in the body as Archbee will render it twice. - `slug:` the URL path under `docs.flipper.net/one/`. Example: ```markdown --- title: About Docs slug: resources/about-docs --- ``` ### Adding a new page 1. Create the `.md` file under `docs/...` and set the `title:` and `slug:` fields in the frontmatter. 2. Add an entry for it in `archbee.json` β†’ `structure.docsTree` at the right place in the hierarchy. Ideally, nesting should not go deeper than two levels. 3. Open a pull request to the `public-release` branch. Once merged, Archbee rebuilds the live site. *** ## πŸ“Š Diagrams on Miro ![Miro board example](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/TSRY_teI-TQpjLsh58et0_miro-example.png "Flipper One β€” Docs Miro board") All diagrams used in the Developer Portal, architecture overviews, flow charts, and conceptual visuals are designed on the [Flipper One β€” Docs Miro board](https://miro.com/app/board/uXjVJ6y839o=/). The board is publicly viewable: anyone can open it, inspect existing diagrams and templates, and export a copy for reference or offline editing. :::hint{type="info"} Spotted an error or have an idea for a new diagram? Share them with us in a [pullΒ request](docId:5qbNeaaFeDvyK2XIS_-Zv). ::: *** ## 🎨 Illustrations on Figma ![Figma file example](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/RruijLDnKvH85aOvi4qG-_figma-example.png "Flipper One β€” Docs Figma file") Illustrations and decorative graphics are designed in the [Flipper One β€” Docs Figma file](https://www.figma.com/design/HcwlmmIJlW4LoiQu4RtwwH/Flipper-One-%E2%80%94-Docs). Like the Miro board, the Figma file is publicly viewable: you can browse every frame, inspect layers, and export illustrations at any resolution. :::hint{type="info"} Have an idea for a new illustration or a tweak to an existing one? Share them with us in a [pullΒ request](docId:5qbNeaaFeDvyK2XIS_-Zv). ::: *** ## How to contribute :::hint{type="info"} To contribute to the Docs sub-project, you need to have a GitHub account. You can create one on the [GitHub website](https://github.com/signup). ::: ![How to contribute to the Docs](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/hJiiniIizLun44Ii-kYfS_how-to-contribute-about-docs.jpg) **Before you start:** Check open tasks in the [task tracker](https://github.com/orgs/flipperdevices/projects/10) to see what the team is already working on or where help is wanted, and skim the [Markup reference](docId\:L8V_N7C30UTmEEIh2vl-7) and [Style guide](docId\:C55XJ4-oFpj-7aKREaXCI) pages to get familiar with the supported syntax and our writing style. ::::WorkflowBlock :::WorkflowBlockItem Fork the [flipperone-docs](https://github.com/flipperdevices/flipperone-docs) repository. ::: :::WorkflowBlockItem Edit Markdown files in the `docs/` folder. ::: :::WorkflowBlockItem Submit your work as a **pull request** to our GitHub repository. ::: :::: *** ### Submit your fix or guide as a pull request If you’ve spotted an error, want to clarify a section, or want to add a new guide, you’re welcome to contribute. Fork the repository, make your changes on a new branch, and submit a pull request to the original repository: ::::WorkflowBlock :::WorkflowBlockItem **Read the reference docs.** Skim the [Markup reference](docId\:L8V_N7C30UTmEEIh2vl-7) and [Style guide](docId\:C55XJ4-oFpj-7aKREaXCI) to learn the supported syntax and our writing style. If you're using an AI assistant to write or edit, point it to both files so it knows which syntax to use and how to match our writing style. ::: :::WorkflowBlockItem **Fork the repository.** Go to [flipperone-docs](https://github.com/flipperdevices/flipperone-docs) and click **Fork** in the upper-right corner. Your fork opens on the `public-release` branch, which is the production branch connected to the live site. All your work happens here. ::: :::WorkflowBlockItem **Edit or create an **`.md`** file.** In your fork, find the file you want to edit under `docs/`, or create a new one in the appropriate subfolder. Follow the syntax shown on the Markup reference page because some Markdown features behave differently in Archbee. ::: :::WorkflowBlockItem **(Optional) Add images.** If your change includes images, diagrams, or screenshots, upload them to `docs/files/pics/` and reference them with a relative path: ```markdown ![Alt text](/files/pics/your-image.png "Caption") ``` Use descriptive, lowercase filenames with hyphens (for example, `gpio-pinout.png`). Keep images under 1Β MB. ::: :::WorkflowBlockItem **(Optional) Register the new page in **[archbee.json](https://github.com/flipperdevices/flipperone-docs/blob/public-release/archbee.json)**.** Place it in the sidebar hierarchy (no deeper than two levels) β€” see [How archbee.json works](docId:5qbNeaaFeDvyK2XIS_-Zv) for the syntax. It’s okay to skip because we’ll update the file after merging your PR. ::: :::WorkflowBlockItem **Create a branch and commit.** Name the branch `nickname/what-changed` (for example, `john/github-integration-update`). Keep commit messages concise (for example, `Update: rename authentication to auth`). ::: :::WorkflowBlockItem **Open a pull request from your branch to the original repository.** The target is pre-selected to `public-release` β€” leave it as is. Add a clear title and description, and ideally attach screenshots and a link to the related open task. Make sure **Allow edits by maintainers** is ticked so we can apply small wording or syntax fixes directly to your PR. ::: :::: Once your pull request is merged into `public-release`, Archbee automatically picks up the changes and rebuilds the live site at [docs.flipper.net/one](https://docs.flipper.net/one). *** ### Suggest your change as a comment on an open task :::hint{type="info"} **⚠️ Contributions only β€” no flooding** To keep collaboration productive, please keep comments on-topic. Open tasks are for contribution-related discussion only. If you have an idea or concern, first turn it into a concrete contribution and share it as a comment on a task. For general questions or discussions, you’re always welcome to join the conversation on [socialΒ media](https://x.com/Flipper_RND) or [Discord](https://discord.com/invite/flipper)! ::: Open tasks that need the community’s help are labeled **help wanted**. If you have ideas on how to improve a page, you can contribute by commenting on the task and attaching screenshots, videos, or links: :::::WorkflowBlock :::WorkflowBlockItem **Pick a task.** In the [Docs GitHub project](https://github.com/orgs/flipperdevices/projects/10), browse the open tasks and click the one labeled **help wanted** that you want to contribute to. ::: ::::WorkflowBlockItem **Write your suggestion.** In the comments section, clearly describe your suggestion and, if helpful, attach a screenshot, video, or link to a draft pull request. :::hint{type="info"} **Important:** If you share a link, ensure the content is accessible to others. ::: ![](https://api.archbee.com/api/optimize/3StCFqarJkJQZV-7N79yY/7P5f3QhR3h-dqFuE-uJ1g_docs-good-vs-bad-comment.png) Attachment size limit: - Images: 10Β MB - Videos: 100Β MB :::: :::WorkflowBlockItem **Click Comment** to submit. ::: ::::: We review all comments carefully! We may ask additional questions about your idea in the task thread, so please watch for GitHub notifications in your email.