How orcid/orcid-api-tutorial works
Project type and purpose
• This is a static-site documentation project built with MkDocs (Python-based).
• The purpose is to produce and deploy an ORCID API tutorial website.
File structure
• Top-level files:
• mkdocs.yml – MkDocs configuration
• README.md – setup + deployment instructions
• Source content directory:
• docs/ – contains .md pages (index.md, get.md, post.md, etc.), CSS overrides, and images.
• Custom theme directories:
• cinder/ – a custom MkDocs theme (HTML templates, CSS, JS, fonts, images)
• mkdocs-material/ – likely the upstream Material theme code or a local clone for customization.
• Build output:
• site/ – the generated static website (HTML, CSS, JS, images).
• Other:
• .DS_Store files (macOS metadata).
README for additional insights
• Dependencies: Python ≥2.6, pip, MkDocs.
• Development: mkdocs serve spins up a local server that watches docs/ and reloads on edits.
• Deployment: mkdocs gh-deploy builds to site/ and pushes to the gh-pages branch on GitHub.
Main components and interactions
a. Components
1. Source Content (docs/)
2. Configuration (mkdocs.yml)
3. Theme Engine
– cinder/ (custom templates & assets)
– mkdocs-material/ (base theme)
4. MkDocs CLI & Python runtime
5. Build Output (site/)
6. Version Control & Deployment
– Git repo (master & gh-pages branches)
– GitHub Pages
b. Relationships / Data flow
1. Author updates .md files under docs/ and tweaks mkdocs.yml.
2. The MkDocs CLI (Python process) reads config + content + theme templates.
3. Theme engine applies templates (cinder & material) to markdown → HTML, bundles assets.
4. Static site artifacts are written to site/.
5. mkdocs gh-deploy pushes site/ contents to gh-pages branch on GitHub.
6. GitHub Pages serves the site at https://orcid.github.io/orcid-api-tutorial.
c. Architectural patterns / design principles
– Static site generation: separation of concerns (content vs presentation vs build).
– Theming abstraction: overrides in cinder/ layered on top of mkdocs-material/.
– CI/CD‐style deploy via mkdocs gh-deploy.
d. Key technologies / frameworks
– Python, MkDocs, mkdocs-material theme, custom cinder theme
– Git & GitHub Pages for hosting
– CSS & JS assets (Bootstrap-based, Font-Awesome, Highlight.js)