Landing page optimization: conversion, performance, SEO, and accessibility recommendations

[cdcavell]

Summary

I reviewed the live landing page at https://asibackbone.github.io/Learning/index.html (source: docs/index.md, DocFX modern template plus docs/templates). The basics are already good: canonical URL, description, full Open Graph and Twitter tags with a 1200×630 image, JSON-LD WebSite/Organization, lang="en", one H1, a sitemap, and alt text on the one image. Load time is fine (about 450 ms to DOMContentLoaded and 860 ms to load on a warm connection).

The recommendations below are about the next level: getting a first-time visitor to the right path faster, cutting unneeded bytes, and cleaning up a few SEO and accessibility details. They're grouped by area, and each has a suggested priority.

---

1. Content and conversion (highest impact)

The page has about 1,060 words. On a phone, the first screen shows only the branding, the ASI disambiguation paragraph, and the tagline. No link to start learning shows up until the second screen.

#	Recommendation	Priority
1.1	Add clear calls to action near the top. Put 2–3 prominent links right under the tagline, for example Get Started, Find Your Path, and Browse Articles. Right now "Start Here" is a plain H2 followed by prose.	High
1.2	Shorten the intro. Turn the "educational layer", "ASI means…", and "it exists to…" paragraphs into one sentence. Move the Artificial Superintelligence Alliance disclaimer lower on the page (or into "What This Project Is Not"). It matters, but it shouldn't be the second thing a reader sees.	High
1.3	Turn "Start Here" into a picker. The five "if you are X, go to Y" paragraphs work well as a short list or small cards: New → Getting Started, Have a problem → Find Your Path, Evaluating by role → Adoption Personas, New vocabulary → Terminology, Already on ASP.NET Core authz → When Authorization Is Enough.	High
1.4	Show the core model visually. The two flows (Intent → … → Audit residue, and Problem → … → Working repository example) are ```text code blocks with ↓ arrows. Screen readers read them as preformatted text, and they look like code. Use a Mermaid diagram (DocFX modern supports it) or a styled ordered list. Also consider moving the Intent → Audit flow higher, since it's the page's main idea.	Medium
1.5	Use cards for "Choose a Learning Path". There are 10 sections, each an H3, a paragraph, and an "Explore →" link, which makes a long vertical scroll. A responsive 2–3 column card grid (custom CSS in docs/templates/public/main.css) would cut the page length roughly in half on desktop. Consider putting the paths in a suggested order (Beginner → Advanced) or tagging each with a level, using the same labels the repo already has (beginner / intermediate / advanced).	Medium
1.6	Move or collapse the reference sections. "Canonical Does Not Mean Universal", "What This Project Is Not", and "Project Status" are useful but don't help people get started. Move them to Getting Started or an About page and leave one-line links, or put them in <details> blocks.	Medium
1.7	Show that the project is active. "Living project — active development" is a claim with no evidence. Add a small "Latest articles / recently added" list (for example, the newest article on AI agent authority, #333) or a count such as "5 executable samples".	Low

2. Performance

Measured on page load:

Resource	Transfer	Notes
public/es-*.min.js	~309 KB	Lazy chunk (syntax highlighting/Mermaid) loaded even though the landing page only has text blocks
bootstrap-icons-*.woff2	~131 KB	Whole icon font loaded for a few UI icons
docfx.min.css	~48 KB
docfx.min.js	~37 KB
search-worker.min.js	~20 KB	Search worker starts immediately
index.json (search index)	~3.0 MB uncompressed	Loaded by the worker. Size will grow with each article
toc.json	fetched twice	Duplicate request

#	Recommendation	Priority
2.1	Make the search index smaller or load it later. 3 MB will keep growing. Options: start the search worker only when someone focuses the search box, exclude _site sections such as samples/code listings from indexing (_noindex / searchScopes), or strip index content down to title + summary.	High
2.2	Don't load the ~309 KB es-* chunk on pages that don't need it. Check why it loads on the landing page. If the Mermaid change in 1.4 is adopted, this is fine. Otherwise make the highlighting/Mermaid load conditional.	Medium
2.3	Preload the icon font and the logo, or replace the few Bootstrap Icons used with inline SVG. Add <link rel="preload" as="font" type="font/woff2" crossorigin> in the template head.	Low
2.4	Find out why toc.json is fetched twice (possibly a template override in docs/templates plus the default) and remove the duplicate request.	Low
2.5	Serve the logo as WebP/AVIF or inline SVG, with explicit width/height to prevent layout shift. The 50 px PNG is small, but it's loaded on every page.	Low

3. SEO and metadata

#	Recommendation	Priority
3.1	Fix the duplicate title. The <title> is ASI Backbone Learning | ASI Backbone Learning because the H1 matches _appTitle. Set page-level title: front matter in docs/index.md to something descriptive, e.g. Governed Execution & Secure .NET Architecture Tutorials, or remove the suffix on the home page in the template. This is the most visible SEO fix.	High
3.2	Rewrite the H1 around search intent. Keep the brand, but add a subtitle with keywords, or make the H1 describe the value ("Practical .NET architecture for governed execution…") with the brand in the header logo.	Medium
3.3	Make descriptions consistent. The JSON-LD description starts with "Accountable Systems Infrastructure (ASI) Backbone Learning provides…", while the meta/OG description is different. Pick one wording.	Low
3.4	Don't publish the build manifest. /Learning/manifest.json (~38 KB) is the DocFX build manifest, not a web app manifest. It exposes the internal file layout and can confuse tools that look for a PWA manifest. Exclude it from the published _site or rename it. Optionally add a real site.webmanifest with theme-color.	Low
3.5	Handle robots.txt. https://asibackbone.github.io/robots.txt returns 404. It can only be served from the org's asibackbone.github.io user-site repo, so either add one there that points to /Learning/sitemap.xml, or submit the sitemap directly in Search Console / Bing (IndexNow is already set up).	Low
3.6	Add BreadcrumbList / ItemList JSON-LD for the learning paths so search results can show sitelinks.	Low

4. Accessibility and UX

#	Recommendation	Priority
4.1	Add a "Skip to content" link. No skip link was found, and keyboard users have to tab through the navbar and search on every page.	Medium
4.2	Give arrow links an accessible name. Several links read "Explore →". Make sure the link text is unique without the heading (for example "Explore Architecture" is fine; check all 10) and hide the decorative → with aria-hidden.	Low
4.3	Improve the right-side "In this article" TOC. It has 20 entries and is noisy on a landing page. Consider _disableToc: true / _disableAffix in the home page front matter once 1.5 and 1.6 are done.	Low
4.4	Check color contrast of the bold tagline and blockquote ("Read it. Run it. Question it. Improve it.") in both light and dark themes.	Low
4.5	Remove the lone "Home" breadcrumb on the home page. It adds no information.	Low

5. Measurement

#	Recommendation	Priority
5.1	Add a Lighthouse CI step (or treosh/lighthouse-ci-action) to the Pages workflow with budgets for the landing page, e.g. performance ≥ 90, accessibility ≥ 95, SEO = 100, total JS ≤ 450 KB. This keeps regressions from coming back as the site grows.	Medium
5.2	If analytics are acceptable for the project, add a privacy-friendly option (e.g. GoatCounter / Plausible) to see which "Start Here" entry points people actually use and inform 1.3 and 1.5.	Low

---

Suggested order of work

1. Quick wins (one PR): 3.1 duplicate title, 4.1 skip link, 4.5 breadcrumb, 3.3 description consistency, 2.4 duplicate toc.json.
2. Landing page restructure (one PR): 1.1, 1.2, 1.3, 1.5, 1.6, plus 4.3.
3. Visual model: 1.4 Mermaid diagrams (together with 2.2).
4. Search payload: 2.1 lazy/lighter search index.
5. Guardrails: 5.1 Lighthouse CI.

Acceptance criteria

• A link to start learning is visible on the first screen at 375×812
• <title> is no longer duplicated
• The landing page loads without fetching the 3 MB search index until search is used
• No duplicate toc.json request
• Skip link is present and works
• Lighthouse (mobile) scores are recorded before and after in the PR description

Review done on 2026-09-13 against commit 351fd97.