How michiganadc/dmsc-madc works
Main Components
• Quarto Rendering Engine: This is the core processor that converts .qmd files into a static website. It’s configured via the _quarto.yml file.
• Content Files: These include all the .qmd files (e.g., index.qmd, about.qmd, publications.qmd, etc.) as well as other documents (data_dictionary.qmd, label_libraries.qmd, etc.), which serve as the website’s pages.
• Assets and Resources: The assets directory (with subdirectories for CSS, images, label libraries, and team bios) holds all design, branding, and media resources.
• Deployment Pipeline: This includes GitHub Actions workflows from the .github/workflows directory and the .nojekyll file ensuring proper GitHub Pages deployment.
• Supporting Files/Configuration: Files like README.md and setup notes offer contributor documentation, while the file tree indicates a clean separation of content, configuration, and resources.
Detail the Relationships and Interactions
• The Quarto engine (as configured in _quarto.yml) processes the .qmd files using styles from assets/css and supporting scripts/styles from README_files/libs.
• Rendered content is output into a designated folder (docs as per instructions), which is then served by GitHub Pages.
• The development environment (i.e., VS Code with the Quarto extension) is used to modify the content and preview changes locally before committing.
• The GitHub Actions workflow (found under .github/workflows) automates any tasks related to publishing or continuous deployment when changes are pushed to the main branch.
Architectural Patterns and Design Principles
• Static Site Architecture: The overall design is that of a static website built from source content (Markdown) and rendered by a build tool (Quarto).
• Separation of Concerns: Content is maintained separately in .qmd files, styling and scripts in the assets/ and README_files directories, and the build configuration in _quarto.yml.
• Declarative Configuration: The project uses a declarative configuration (Quarto’s YAML files) to determine the output and deployment directories, ensuring consistency across development and deployment.
• Continuous Deployment: The integration with GitHub Pages (via changes to docs, .nojekyll, and automated workflows) ensures that every change can be deployed directly from the repository.
Relevant Technologies, Frameworks, and Tools
• Quarto: The static site generator and publishing engine as the core technology.
• Git and GitHub: Version control and hosting that enable collaborative development and deployment through GitHub Pages.
• Visual Studio Code: The recommended IDE for development with the Quarto extension for live preview and document rendering.
• CSS and Bootstrap (as seen in the README_files/libs): Indicating the styling framework in use.
Additional Details
• Provide annotations to denote that updates in the .qmd files or assets are processed via Quarto, which applies the site configuration provided by _quarto.yml.
• Notes on how GitHub Actions automates the rendering process and deployment to GitHub Pages, emphasizing the end-to-end workflow from commit to live site.