PLAN.md

QMCSoftware Website Prototype Plan

Purpose and architecture

This repository will provide the single public-facing website for the QMCSoftware organization. Quarto source lives on main, renders to _site/, and is published by GitHub Actions to the gh-pages branch. The canonical custom domain is qmcsoftware.org.

Technical documentation remains with each software repository and is linked from this site. The website adds a shared public entry point; it does not replace project documentation.

Guiding principles

• Keep the prototype small, navigable, and easy to maintain.
• Reuse proven structural and deployment ideas without importing course or slide architecture.
• Treat maintained project sources as authoritative and avoid speculative copy.
• Separate source from generated output and validate each phase before adding complexity.
• Make later content migration explicit and reviewable.

Phased roadmap

Phase 0 — Confirm direction and inspect references

• Confirm the repository roles, source branch, output directory, publish branch, custom domain, and scope exclusions.
• Inspect the starting QMCPy-only prototype files.
• Inspect relevant Quarto and deployment patterns in MATH565Fall2026.
• Confirm the maintained documentation and GitHub destinations from QMCSoftware.

Phase 1 — Prepare the repository

• Replace the standalone index.html with Quarto source.
• Add ignore rules for generated Quarto output.
• Preserve the root CNAME during prototype setup.
• Add repository purpose, local-render instructions, project guidance, roadmap, and status documentation.
• Avoid unnecessary runtime dependencies; no requirements.txt is needed for the current non-executable content.

Phase 2A — Establish the original site skeleton

• Configure a Quarto website that renders to _site/.
• Add Home, Blogs, News & Events, Community, Documentation, and GitHub navigation.
• Add initial Home and About sources.
• Create blogs/, news/, community/, assets/, styles/, and workflow structure.
• Link Documentation to the existing MkDocs site and GitHub to the primary QMCSoftware repository.

Phase 2B — Establish the visual foundation

• Add a restrained initial color palette, typography, spacing, hero, and responsive button treatment.
• Widen the standard content column to improve the use of desktop space while retaining readable prose line lengths.
• Keep the styling local and independent of classroom-specific styles.
• Review the prototype with collaborators and align it with any approved QMCSoftware visual identity or assets.
• Complete browser-based responsive and accessibility review.

Phase 3 — Convert to the QMCSoftware umbrella

• Replace the QMCPy-specific homepage with an organization-wide homepage.
• Add a Software section for QMCPy, QMCToolsCL, QuasiMC.jl, and LDData.
• Add a Publications prototype without inventing a complete bibliography.
• Update shared navigation, metadata, footer, and organization-wide copy.
• Keep each project's detailed documentation in its maintained repository.
• Retain qmcpy.org and the existing CNAME during the initial transition.
• Set qmcsoftware.org as the long-term canonical domain and custom domain.
• Verify any required redirects from the former domain.
• Approve an organization-level visual identity and navbar mark, if any.

Phase 4 — Refine the homepage

• Add a concise prototype introduction and primary documentation/GitHub actions.
• Add clear pathways to learning, updates, and community information.
• Replace provisional wording only with collaborator-approved public copy.
• Add approved imagery, examples, or impact highlights if they provide clear value.

Phase 5 — Migrate the blog

• Migrate “Why Add Q to MC?” as the first self-contained Quarto post, preserving its authorship, mathematical explanation, equations, figures, and captions.
• Revise “Why Add Q to MC?” as a living article with one last-revised date, qualified convergence claims, and practical guidance.
• Migrate “A QMCPy Quick Start” as a self-contained Quarto post, preserving its original authorship, date, Keister example, code, mathematics, output, references, and figure.
• Establish listing metadata and a discoverable Blogs index.
• Inventory the existing 18 posts and their assets without modifying the source repository.
• Define consistent Quarto post metadata, paths, authorship, and categories.
• Use one date value per post as the last-revised date, label it “Last revised,” and sort the archive by that value without separate first-published metadata.
• Convert the complete 18-post archive, including MkDocs snippets, callouts, image groups, internal links, and mathematical delimiters.
• Preserve the original visible content of 17 posts and retain the approved living-article revisions to “Why Add Q to MC?”.
• Verify last-revised dates, authors, local links, code, mathematics, and all 48 images in a complete local render and browser review.
• Add the two May 2026 QMCPy documentation blogs on iteration logs and resuming integrations, retaining links to their executable notebooks.
• Expand the current website archive from the historic 18 posts to 20 posts.
• Define and verify redirects or canonical handling for legacy URLs.
• Publish the complete archive only after collaborator review.

Phase 6 — Build news and events

• Add the section entry page without invented announcements.
• Add a sourced prototype news item and a discoverable News & Events listing.
• Define lightweight metadata and archive conventions.
• Add only confirmed news, talks, workshops, releases, and events.
• Decide how past and upcoming events should be presented.

Phase 7 — Develop community content

• Link to maintained community and contribution resources.
• Add a Website-owned, community-maintained directory of QMC software across organizations and ecosystems.
• Add an extensible list of university courses using QMCSoftware, beginning with the Fall 2025 and Fall 2026 MATH 565 offerings.
• Agree on the intended audience and approved community narrative.
• Add verified governance, contributor, support, and participation information without duplicating maintained technical guidance.
• Review names, roles, affiliations, and acknowledgements with collaborators before publication.

Phase 8 — Integrate documentation pathways

• Add links to maintained project documentation and repositories.
• State clearly that technical documentation remains with each project.
• Review reciprocal links from the software repositories and documentation.
• Verify that users can distinguish public, learning, API-reference, and contribution destinations.

Phase 8A — Develop publications

• Add a selected local YAML publication catalog.
• Render ordinary publication records directly from YAML on the Publications page, without per-publication folders or QMD files.
• Sort the curated website catalog by year descending and title ascending, grouping ordinary publications under year headings.
• Add a reviewed prototype publication with publisher, DOI, and arXiv links as a hand-written featured introduction.
• Document the one-record YAML contribution convention.
• Correct and enrich the corresponding AcademicLib record in a separately authorized AcademicLib task.
• Agree on bibliography scope, review ownership, and migration priorities.

Phase 9 — Test the site

• Validate the Quarto configuration and a complete local render.
• Inspect generated page structure, internal destinations, external destinations, and custom-domain output.
• Perform browser checks at desktop and mobile sizes.
• Run accessibility, HTML, and link checks appropriate to the final content.
• Test from a fresh clone with the documented Quarto setup.

Phase 10 — Validate deployment

• Add GitHub Actions rendering from main to _site/ and publishing to gh-pages.
• Explicitly preserve CNAME in the rendered publish directory.
• Review repository Pages settings and workflow permissions.
• Trigger the workflow on GitHub and verify the gh-pages branch contents.
• Verify HTTPS and qmcsoftware.org after deployment.

Phase 11 — Collaborator review and prototype decision

• Review information architecture, visual direction, and provisional copy with QMCSoftware collaborators.
• Record requested changes and resolve launch-blocking issues.
• Agree on ownership and cadence for blog, news, and community updates.
• Authorize and locally validate the historic 18-post blog migration.
• Approve and publish the completed historic 18-post archive.
• Authorize migration of the two newer resume and iteration-log blogs.
• Approve and publish the completed 20-post archive after pull-request review.

Phase 12 — Coordinate work across machines

• Define durable repository rules, a direct-to-main author workflow, and a concise operational handoff for Website collaborators and agents.
• Make synchronization, branch selection, validation, and publication expectations explicit.
• Use the workflow during several real Website tasks and refine it only in response to observed coordination problems.