How speciesfilegroup/taxonpages works
Project Type and Purpose
• TaxonPages is a static site generator that serves taxon pages. It pulls data from TaxonWorks’ API (with plans to support additional biodiversity data sources) and supports customization via markdown, Vue components, custom layouts, panels/plugins, and theme settings.
• The README details installation, configuration (especially for API endpoints and analytics), and customization (pages, layouts, panels), which shows its focus on modularity and extensibility.
Analyzing the File Structure
• Top-level directories:
• .github: Contains GitHub Actions workflows (e.g., deploy.yml), issue templates, and dependabot configuration. This indicates automated deployment/build (likely triggering the static site build process).
• config: Central hub for configuration (API details, analytics settings, style, and taxon page panel layouts). It drives how the site consumes external data (from TaxonWorks’ API) and determines appearance and page behavior.
• pages: Contains markdown content files that are converted into pages, hinting at a rendering pipeline that likely uses a tool like vite-plugin-md.
• public: Likely serves as static assets and holds instructions/documentation (a public README) that may complement the built site.
• Other root files (README.md, .gitignore) support project documentation and repository hygiene.
Main Components & Their Roles
A. Content & Presentation Layer:
• Frontend – This is where Vue components and markdown pages live. The pages directory provides content that routes are automatically generated from filenames. Custom layouts (via layouts/default.vue if created) and styling (Tailwind CSS via config/vendor/tailwind.config.js and config/style/theme.css) support dynamic customization of the user interface.
• Global Components – Auto-import mechanism for Vue components (as outlined in the README) provides UI elements like buttons, cards, maps, modals, etc.
B. Configuration & Customization Layer:
• Config Files – The config folder contains multiple YAML files for API configuration, routing, analytics, theme, and even taxon page layouts (taxa_page.yml). This layer allows the site to be tailored without code changes.
• Panels/Plugins – The documentation shows how to add external panels (e.g., creating panels inside a panels directory in the setup branch) to extend taxa pages, enabling modularity.
C. Data Integration:
• API Component – config/api.yml configures connections to the TaxonWorks API (or potentially other APIs in future versions). This component is central to fetching taxon data.
D. Deployment & Build Pipeline:
• GitHub Actions – Workflows (in .github/workflows/) trigger deployment (e.g., deploy.yml) to build the site (using NodeJS and Vite) and then deploy it (likely to the gh-pages branch for GitHub Pages hosting).
• Branch Strategy – The repository uses multiple branches (main vs. setup) where configuration changes occur before being built.
E. External Services Integration:
• Analytics – The system is pre-configured for multiple analytics services (Google Analytics, GTM, Facebook Pixel, etc.) as specified in the config files.
Relationships & Data Flow
• Configuration files feed into the build process to define API endpoints, analytics, layout, and styling.
• The content layer (pages and Vue components) utilizes these configurations to render dynamic taxon pages.
• Custom panels are integrated into layout configuration (taxa_page.yml) and then loaded as Vue components during the rendering.
• The build process (driven by GitHub Actions) takes the source files (from main or setup) to generate a static site, which is then served via GitHub Pages.
• Data flow from TaxonWorks API (or external APIs) into the content rendering components.
• The trigger from GitHub (via actions) kicking off the build and deployment.
• Interactions between configuration settings (YAML files) and rendered components.
Architectural Patterns and Design Principles
• Modularity – Separation between configuration, content (pages), and UI components.
• Extensibility – The ability to add custom panels, multiple layouts, and plugins.
• Static Site Generation – Leveraging build pipelines (NodeJS/Vite) and GitHub Pages for speedy front-end delivery.
• Integration of both client-side (CSR with Vue) and server-side considerations (via SSR hooks and placeholders for client-only libraries).
Final Steps
• Flow: GitHub Fork → Configuration Setup (setup branch) → GitHub Actions build → Static Site Generation → Deployment to GitHub Pages → Page served to end users.