Open Share Doc Site

Purpose: This repository hosts the static documentation site for Open Share (project docs live in the open-share-meta repo). The site uses MkDocs (Material theme) to present high-level architecture, diagrams, roadmap and developer guides — with Mermaid diagrams rendered cleanly.

This repo functions as the presentation layer:

• mkdocs.yml — MkDocs configuration (theme, plugins, nav).
• content/ — Git submodule that points to open-share-meta (the canonical docs).
• assets/ — site-level assets (logo, CSS, JS, hero images).
• .github/workflows/ — CI workflow to build & publish to GitHub Pages.

---

Quick start (for doc authors / maintainers)

# clone the site repo
git clone git@github.com:your-org/open-share-doc-site.git
cd open-share-doc-site

# init / update the docs content submodule (open-share-meta)
git submodule update --init --recursive

# optional: update submodule to latest main
cd content
git checkout main
git pull origin main
cd ..

# create venv & install deps
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt  # or install mkdocs + plugins manually

# run preview server
mkdocs serve

The content/ directory contains the authoritative markdown files (ARCHITECTURE.md, ROADMAP.md, diagrams/*, etc.). Edit docs there and commit in the open-share-meta repo.

---

Repo structure

open-share-doc-site/
├─ .github/
│  └─ workflows/
│     └─ build-and-publish.yml   # CI: build docs and deploy to gh-pages
├─ mkdocs.yml                    # MkDocs config (Material + plugins)
├─ content/                      # git submodule -> your-org/open-share-meta
├─ assets/
│  ├─ images/                    # logo, hero GIFs
│  ├─ stylesheets/extra.css      # small visual polish
│  └─ javascripts/mermaid-init.js
├─ README.md
└─ requirements.txt              # optional pinned Python deps

---

Add or update the content submodule

To add the open-share-meta repository as the content submodule:

git submodule add --name open-share-meta https://github.com/your-org/open-share-meta.git content
git submodule update --init --recursive
git commit -m "Add open-share-meta content submodule"
git push

To update the submodule to the latest upstream:

cd content
git fetch origin
git checkout main
git pull origin main
cd ..
git add content
git commit -m "Update content submodule to latest"
git push

---

Build & deploy (CI)

This repo includes a GitHub Actions workflow (.github/workflows/build-and-publish.yml) that:

1. checks out the repo with submodules,
2. installs MkDocs + Material + required plugins,
3. builds the static site (mkdocs build),
4. deploys to gh-pages via peaceiris/actions-gh-pages (or equivalent).

You can run a local build:

mkdocs build
# site/ will contain the static site

---

Editing guidelines

• Docs content edits: make them inside open-share-meta (submodule). Submit PRs against that repo for content changes.
• Site theme / config edits: change mkdocs.yml, assets/ or workflow files here (open PR in open-share-doc-site).
• Mermaid diagrams: keep large Mermaid blocks in content/diagrams/*.md. The mermaid2 plugin renders them reliably.

---

Contributing

1. Fork the appropriate repo (open-share-meta for content, open-share-doc-site for site/theme).
2. Create a feature branch.
3. Open a PR with clear summary and preview screenshots (if UI changes).
4. CI will build the preview (mkdocs serve locally for authors).

---

Tips to keep the docs modern & awesome

• Add animated GIFs showing discovery → handshake → transfer.
• Keep ARCHITECTURE.md and diagrams/* as the single source of truth.
• Announce large doc changes in PR description and include before/after screenshots.
• Use git-revision-date-localized plugin to communicate freshness; useful for architecture pages.

---

License

This site and the example site config are licensed under the same license as the docs content (check content/LICENSE). If you keep the same license across both repos, add appropriate LICENSE files to both.

---