Notificator Project Docs Contributor Guide

This repository contains the Notificator Project documentation site. It includes end-user guides for WordPress, Strapi, the web dashboard, mobile apps, MQTT, and connected devices, plus developer integration guides for Astro, the hosted API, and the official Node.js SDK.

Current integration packages:

• @notificator-project/api@0.1.0 for trusted Node.js server applications
• @notificator-project/strapi-extension@0.1.1 for the Strapi 5 preview
• @notificator-project/astro@0.1.0 for trusted Astro server workflows and successful-build alerts

Web dashboard and shared accounts

Users can create an account, generate API keys, read notifications, and monitor devices through the web dashboard (beta) or mobile app. The Web Dashboard Guide documents session-only MQTT credentials, optional encrypted account saving, restoration and removal, device status, and signed OTA controls. The MQTT Broker Setup guide explains the storage choices for each client. Plugin and mobile retrieval of the shared account configuration remains future work; those clients still use their own saved settings. The API-key guide keeps its existing mobile-api-key-creation URL for compatibility, but covers both clients. Mobile push still requires the mobile app.

Tech Stack

• Astro 6
• Starlight
• Markdown and MDX content collections

Attribution

This documentation site is built with the Astro Starlight docs framework.

• Astro: https://astro.build/
• Starlight: https://starlight.astro.build/

Prerequisites

• Node.js 22.12.0 or newer
• npm

Quick Start

cd docs
npm install
npm run dev

Local site: http://localhost:4321

Available Commands

npm run dev      # Start local dev server
npm run build    # Create production build
npm run preview  # Preview production build locally

Project Structure

• src/content/docs/index.mdx: Developer overview landing page
• src/content/docs/guides/: Task-based documentation for users and developers
• src/content/docs/reference/: API reference pages
• astro.config.mjs: Starlight config, including sidebar navigation

Authoring Workflow

1. Add or edit a page in src/content/docs/guides/ or src/content/docs/reference/.
2. Include frontmatter at minimum:

---
title: Page Title
description: One-sentence summary shown in previews/search
---

3. If the page is new, register it in the sidebar in astro.config.mjs.
4. Run npm run dev and verify rendering, links, headings, and code blocks.
5. Run npm run build before opening a PR.

Writing Standards

• Keep guides action-oriented and step-by-step.
• Prefer short sections with explicit outcomes.
• Match public API examples to the production public endpoint: api.notificator-project.com.
• Keep Node.js examples aligned with the current @notificator-project/api package and its fixed hosted endpoint.
• Keep Astro examples aligned with @notificator-project/astro, Astro 5 or newer, and server-only public_client key usage.
• Keep the WordPress delivery endpoint distinct: wpnotif.notificator-project.com is used by the plugin for optional remote delivery.
• Keep API key scopes explicit: wordpress_server for WordPress, strapi_server for Strapi, and public_client for the public Notify API.
• Keep user guide content and developer guide content clearly separated.
• Validate every command and request payload you document.

Definition of Done (Docs Changes)

Before opening a PR, confirm all items below:

1. New or changed pages are linked from the sidebar when applicable.
2. Commands and URLs were executed or validated.
3. Internal links are not broken.
4. Build succeeds with npm run build.
5. Language is concise, consistent, and audience-appropriate.

Contributing

You can contribute in two simple ways:

1. Open an issue for bugs, broken links, or unclear docs.
2. Open a pull request if you already have a fix ready.

Both options are welcome. If you are not sure where to start, open an issue first.

Contributions are welcome through the docs repository:

• Repo: https://github.com/notificator-project/Docs
• Open an issue: https://github.com/notificator-project/Docs/issues
• Create a pull request: https://github.com/notificator-project/Docs/pulls

Recommended flow:

1. Fork the repository and create a branch for your docs change.
2. Make your edits and validate locally with npm run dev.
3. Run npm run build to verify the docs compile.
4. Open a pull request with a clear summary and screenshots when UI/output changed.

Troubleshooting

• Astro Node version error: upgrade Node to 22.12.0 or newer.
• Page does not appear in navigation: verify slug entry in astro.config.mjs sidebar.
• Broken links after renaming files: search and update links under src/content/docs/.
• Unexpected stale output: remove old build artifacts and run npm run build again.

Attribution (Project Footer)

• Hosted on Netlify.
• Built with Astro.js.
• Documentation UI powered by Starlight.
• Content authored in Markdown/MDX.
• Source and collaboration hosted on GitHub.

Useful links:

• Netlify: https://www.netlify.com/
• Astro: https://astro.build/
• Starlight: https://starlight.astro.build/
• GitHub repo: https://github.com/notificator-project/Docs