How openbb-finance/openbb-docs works
Project type and purpose
• This is a documentation website built with Docusaurus (a React-based static site generator) and styled with TailwindCSS.
• Its role is to consume markdown content (in the content directory), React components (in src), and static assets, build a static site, and deploy it via GitHub Pages.
• It also integrates Algolia for search, uses Python scripts to generate or preprocess markdown, and employs GitHub Actions for CI/CD.
File structure
• Top-level directories:
• content (all .md/.mdx documentation grouped by product areas: bot, cli, excel, platform, workspace…)
• scripts (Python scripts to auto-generate or update markdown)
• src (custom React components and theme overrides for the Docusaurus site)
• static (static files—images, KaTeX assets, CNAME)
• .github/workflows/deploy-gh-pages.yml (CI/CD pipeline for building and publishing)
• Key config files: docusaurus.config.ts, sidebars.js, tailwind.config.ts, package.json, babel.config.cjs
• Build targets: local dev server (npm start), production static build (npm run build → build/), deploy to gh-pages branch.
• External integrations: Algolia search, GitHub Pages hosting, Python interpreter for scripts.
README for additional insights
• Confirms usage of Node.js ≥16.13.0, Docusaurus, TailwindCSS, Algolia.
• Describes the content pipeline: Python scripts generate markdown in content; markdown is consumed by Docusaurus.
• CI: GitHub Actions builds on push and deploys to GitHub Pages.
• Tests: pytest for platform docs validation.
a. Main components
• Content Authoring Layer
• Markdown files (content/)
• Python scripts (scripts/)
• Presentation Layer
• Custom React components & themes (src/)
• Docusaurus framework (SSG engine)
• TailwindCSS styling
• Build & Deployment Pipeline
• Node.js runtime
• npm install / npm run build
• GitHub Actions workflow
• Hosting & Delivery
• GitHub Pages (static site hosting, CDN)
• External Services
• Algolia Search API
b. Relationships & data flows
1. Developer edits or generates markdown (content/) or React components (src/).
2. Python scripts preprocess or generate markdown files.
3. Docusaurus (via Node.js) reads content/, src/, and docusaurus.config.ts, applies theme and CSS, and outputs static HTML/CSS/JS.
4. GitHub Actions triggers on repo push, runs npm run build, and publishes the build/ directory to the gh-pages branch.
5. End users access the site via GitHub Pages CDN. Runtime search requests from the client go to Algolia’s API.
c. Architectural patterns & principles
• Static Site Generation (SSG) for performance and security.
• Component-based UI (React) with theme overrides.
• Content-as-code: documentation stored and versioned alongside code.
• CI/CD via GitHub Actions.
• Separation of concerns: content (Markdown), presentation (React/TSX + CSS), build (Node), and deployment (GitHub Pages).
d. Key technologies & libraries
• Docusaurus (React SSG)
• React / TypeScript for theming and interactive components
• TailwindCSS
• Python (markdown generation scripts)
• GitHub Actions (CI/CD)
• Algolia (search)
• GitHub Pages (hosting)
Final advice
• Be comprehensive: include all folders or modules only if they play a distinct architectural role (e.g., scripts/ vs. src/components/).
• Data flow, build flow, and runtime interactions.
• Review with content authors and DevOps to ensure nothing is missed.