docs: refine README presentation with banner and fork overview

2026-10-24 12:50:05 +02:00
parent 7a21b2f8e0
commit 3670bb853e
3 changed files with 90 additions and 23 deletions
@@ -1,12 +1,12 @@
 # Repository README standard

-Version: 1.0. Documentation language: English.
+Version: 1.1. Documentation language: English.

 A README should explain the project, help a new reader start it, and point to detailed references. Keep project-specific instructions and existing attribution when applying this standard.

 ## Original projects

-Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Then add a navigation line linking to the level-two sections present in the document.
+Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Follow with a compact project facts table and three or four primary navigation links. Put the complete section navigation inside a `Browse all sections` disclosure.

 Use these level-two headings in this order. Omit sections that do not apply; do not add empty sections or filler just to match the template.

@@ -69,6 +69,22 @@ Borrowing a component or taking inspiration from another project does not by its
 - Preserve existing technical instructions, screenshots, credits, and license notices when reorganizing. Move long references into `docs/` when useful and update links relative to their new location.
 - Never infer a license from a badge, framework, dependency, or a different repository. License choices require an explicit project decision.

+## Presentation
+
+Use the same visual hierarchy for original projects and forks:
+
+1. A plain H1 with the project name.
+2. An optional repository-local SVG banner or real product screenshot, with meaningful alt text. Use a short, factual tagline and a simple product-specific illustration. Keep text readable at narrow widths, and preserve an existing project logo or identity.
+3. A one-paragraph description with a bold opening sentence.
+4. A compact facts table with one row and three or four columns, such as project type, platform, deployment, storage, or license. Include only verified facts.
+5. Three or four primary action links, optionally centered with `<p align="center">`. Use real destinations such as Getting started, Releases, Configuration, and Usage. Do not imply a download exists unless one is available.
+6. A short fork-identity callout for forks, linking to both this repository and upstream and distinguishing their downloads.
+7. A `<details>` block labeled `Browse all sections` with links to every level-two section.
+
+Use short two- or three-column tables for grouped capabilities, station/platform support, fork changes, and documentation links. Keep ordinary prose for explanations. Put long file trees, diagnostic references, and platform-specific details in `<details>` blocks with descriptive summaries. Leave installation prerequisites, required configuration, important limitations, and primary commands expanded. Include blank lines around Markdown inside HTML disclosure blocks so Gitea renders it correctly.
+
+Keep the header compact. Banners should use repository-local assets and render without scripts, external fonts, or network dependencies. Do not add decorative status badges or unverified build/test claims. A banner is optional for small repositories; the facts table, clear primary links, and content hierarchy should still work without one.
+
 ## Maintenance

 Update the README alongside changes to installation, configuration, commands, supported hardware, or release behavior. Check local links, navigation, and Markdown structure before committing. Run a command only when its effects are appropriate; a documentation check must not flash hardware, publish a release, send messages, or start an import.
@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="260" viewBox="0 0 1200 260" role="img" aria-labelledby="title desc">
+<title id="title">Bluetooth-first activity tracking</title>
+<desc id="desc">Hardware sensors at the heart of your recording.</desc>
+<rect width="1200" height="260" rx="22" fill="#0d1b2a"/>
+<path d="M0 238h1200" stroke="#66dfbf" stroke-width="4"/>
+<circle cx="1170" cy="15" r="190" fill="#66dfbf" opacity=".04"/>
+<g font-family="DejaVu Sans,Arial,sans-serif">
+<rect x="42" y="40" width="6" height="18" rx="3" fill="#66dfbf"/>
+<text x="60" y="54" fill="#66dfbf" font-size="13" font-weight="600" letter-spacing="2">OPENTRACKS / ANDROID FORK</text>
+<text x="42" y="118" fill="#f0f6fc" font-size="33" font-weight="700">Bluetooth-first activity tracking</text>
+<text x="42" y="156" fill="#b6c8d9" font-size="16">Hardware sensors at the heart of your recording.</text>
+<text x="42" y="208" fill="#91a9bf" font-size="12" letter-spacing="1">PERSONAL FORK / KAROL LABUS</text>
+<rect x="690" y="89" width="134" height="104" rx="16" fill="#172b42" stroke="#33506a"/><circle cx="714" cy="116" r="5" fill="#66dfbf"/><text x="708" y="148" fill="#f0f6fc" font-size="18" font-weight="600">Sensors</text><text x="708" y="171" fill="#b6c8d9" font-size="12">Speed / cadence</text><path d="M830 141h8m-4-4 4 4-4 4" fill="none" stroke="#66dfbf" stroke-width="2"/><rect x="844" y="89" width="134" height="104" rx="16" fill="#172b42" stroke="#33506a"/><circle cx="868" cy="116" r="5" fill="#66dfbf"/><text x="862" y="148" fill="#f0f6fc" font-size="18" font-weight="600">Recording</text><text x="862" y="171" fill="#b6c8d9" font-size="12">Sensor priority</text><path d="M984 141h8m-4-4 4 4-4 4" fill="none" stroke="#66dfbf" stroke-width="2"/><rect x="998" y="89" width="134" height="104" rx="16" fill="#172b42" stroke="#33506a"/><circle cx="1022" cy="116" r="5" fill="#66dfbf"/><text x="1016" y="148" fill="#f0f6fc" font-size="18" font-weight="600">Export</text><text x="1016" y="171" fill="#b6c8d9" font-size="12">GPX / KML / KMZ</text>
+</g>
+</svg>