Optimize the documentation website for search engines and language models#73
Merged
Merged
Conversation
Give the website the discovery metadata it lacked so readers searching for cost-effectiveness modeling, value of information, and the specific methods reach the relevant page. - _quarto.yml: site-wide meta description, Open Graph and Twitter card tags, a default preview image, html lang, and a head include for structured data. - _structured-data.html: WebSite and SoftwareSourceCode JSON-LD. - robots.txt: allow crawling and point to the generated sitemap. - index.qmd: keyword-rich page title, meta description, keywords, and a lead paragraph of crawlable text describing the package. - tutorials: keywords on the main pages covering the spelled-out terms and the acronyms readers type (EVPI, EVPPI, EVSI, PSA, ICER, CEAC). - images/og-card.png: 1200x630 preview card. Closes #72
Help answer engines and large language models find, read, and cite the documentation, not only classic search crawlers. - llms.txt: a curated markdown map of the site following the llms.txt convention, listing every page with a one-line description in learning order. - robots.txt: name the major answer-engine and language-model crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and others) as welcome; the existing wildcard already granted the same access. - _quarto.yml: copy llms.txt into the built site as a resource. Refs #72
Replace the placeholder sketch with the actual cost-effectiveness plane from the quickstart model: a probabilistic sensitivity analysis of the three-state Markov cohort model, its two treatment clouds shown against standard care with the willingness-to-pay line, so the preview shows genuine package output. Refs #72
Measure the rendered pixel extents of the text and the plot, then slide the plot right until its y-axis label clears the text by a fixed gap, so the two never overlap regardless of label widths. Refs #72
Address three points on the preview card: drop the descriptive caption under the tagline, recolor to the website's teal accent, and replace the scatter cloud with highest-density regions. The plane now shades the 50, 80, and 95% highest-density regions of each treatment, computed from a kernel density estimate of the probabilistic sensitivity analysis draws with mass-based thresholds, in teal and a warm complement. Refs #72
Render the preview card, including the plot title, axes, ticks, and legend, in Poppins, a modern geometric sans that matches the website's font stack, in place of the default serif-adjacent sans. Refs #72
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #73 +/- ##
==========================================
- Coverage 95.51% 95.39% -0.12%
==========================================
Files 40 40
Lines 1918 1955 +37
==========================================
+ Hits 1832 1865 +33
- Misses 86 90 +4 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
pedroliman
changed the title
Change plot_ce_plane to draw each intervention's iterations as nested highest-density regions (the 50%, 80% and 95% regions) by default, with a scatter fallback for too few iterations and kind="scatter" for the previous behavior. Update the report tests and the two tutorials, and their Colab notebooks, that show a cost-effectiveness plane. Style the website plots with Poppins without touching the package: the fonts live under docs/fonts and are installed by the docs workflow, which points MATPLOTLIBRC at docs/matplotlibrc and renders figures at a higher resolution. Bump the freeze cache key so every plot re-renders once to pick up the style. Refs #73
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #72.
Approach
Put the discovery metadata in the site configuration so every page inherits it, and add page-level titles, descriptions, and keywords only where a page targets a specific query. The goal is that a reader searching for cost-effectiveness modeling, value of information, or one of the model engines lands on the relevant page, and that answer engines and language models can find and cite the site. A later round restyled the website plots.
Search engines
docs/_quarto.yml: a site-wide meta description, Open Graph and Twitter card tags with a default preview image,html lang, and a head include for structured data.docs/_structured-data.html:WebSiteandSoftwareSourceCodeJSON-LD.docs/robots.txt: allow crawling and point to the generatedsitemap.xml.docs/index.qmd: a keyword-rich page title, a meta description, keywords, and a lead paragraph of crawlable text describing the package.keywordson the highest-value pages, covering the spelled-out terms and the acronyms readers type (EVPI, EVPPI, EVSI, PSA, ICER, CEAC).Language models
docs/llms.txt: a curated map of the site following the llms.txt convention, listing every page with a one-line description in learning order.docs/robots.txt: name the major answer-engine and language-model crawlers as welcome; the wildcard already granted the same access.Preview image
docs/images/og-card.pngis a 1200x630 card built from the real quickstart model, drawing the cost-effectiveness plane as 50/80/95% highest-density regions in the website's teal accent, set in a modern sans, with the text and plot measured apart at render time.Plot styling and the cost-effectiveness plane
plot_ce_plane(package change): now draws each intervention's iterations as nested highest-density regions (50%, 80%, 95%) instead of a scatter, with a scatter fallback for too few iterations andkind="scatter"for the previous behavior. Covered by new tests; the two tutorials that show a plane, and their Colab notebooks, are updated.docs/fontsand are installed by the docs workflow, which pointsMATPLOTLIBRCatdocs/matplotlibrcand renders figures at a higher resolution for sharp text. The freeze cache key is bumped once so every plot re-renders with the new style.Verification
Package changes are covered by
pytest(274 passing), doctests,ruff, andmypy, and the font-plus-MATPLOTLIBRCmechanism was exercised locally end to end. A full Quarto render was not possible in this environment because the Quarto binary download is blocked, so the documentation workflow renders and deploys on push tomain.