docs(site): serve from saw.ndevuspace.com, and make the pages findable - #1474
Merged
Conversation
The site answered on a github.io address and told search engines nothing about itself beyond a title. Custom domain. `site_url` moves to the domain, and the workflow writes `CNAME` and `robots.txt` into the SITE ROOT rather than `docs/` — mike publishes each build into a version directory, so anything shipped from `docs/` lands in `latest/`, which is the wrong place for both. Pages keeps the domain in repository settings for an Actions deployment; shipping the file as well is what stops a later deploy dropping it. `site_url` deliberately carries the `latest/` prefix. Without it the canonical link on every page, and all 35 URLs in the sitemap, pointed at paths that do not exist on the deployed site — mike serves from `latest/`, not the root. A sitemap of 404s is worse than no sitemap. A released version's pages now name `latest` as canonical, which consolidates ranking there instead of splitting it across versions. Discoverability. A theme override adds Open Graph and Twitter card tags so a shared link renders with a title, a summary and the project mark instead of a bare URL, plus one JSON-LD SoftwareApplication block describing what this is, what it runs on, where to get it and its licence. Everything is derived from mkdocs.yml, so there is no second copy to drift. Verified against a real build, not by reading the config: canonical and sitemap entries resolve under `latest/`, the card tags and JSON-LD are present in the built HTML, sitemap.xml carries 35 URLs, and the root-file step was run to confirm it emits exactly the two files. Closes #1473
…card Follow-through on two things the first pass named and left open. Every one of the 35 pages emitted the same site-wide description, so a search engine saw 35 near-duplicate results and no page said what it was about. Each now carries its own, written to the page rather than derived from its first sentence. The preview image was the 1024x1024 app icon, which a link unfurl shows as a thumbnail. There is now a 1200x630 card built from the mark on its own panel colour, sampled from inside the rounded square rather than the transparent corner, and the Twitter card type is the large-image one that matches it. Also closed out: the MkDocs 2.0 warning is recorded against the pin that already contains it, so the override port is scheduled rather than a surprise; and Search Console ownership is a single value in mkdocs.yml that emits nothing while unset, since verification needs an account only the maintainer has and indexing does not depend on it — robots.txt already points crawlers at the sitemap. Verified on a real build: three sampled pages emit three different descriptions, og:image resolves to the new card, the card type is summary_large_image, and no verification tag is emitted while the value is unset. Refs #1473
…mes this host
Google rejected all 35 URLs in the submitted sitemap: "URL not allowed".
The sitemap is served from saw.ndevuspace.com and every URL inside it
named ndevu12.github.io, and a sitemap may only list URLs on its own
host. The deployed build still carried the old site_url, so the domain
change alone fixes that.
The earlier attempt to fix the canonical links was wrong, though, and
would have shipped a second version of the same class of bug. mike's
mkdocs plugin already appends the version it is deploying:
config['site_url'] = urljoin(config['site_url'], version)
so writing `latest/` into site_url produced `/latest/latest/` on a real
deploy. A plain `mkdocs build` never showed it, because the version
variable is only set while mike is deploying — which is precisely why
the check had to be run the way the deploy runs it, not the way the PR
check does.
site_url is the bare domain again, and the mike plugin is configured
with `canonical_version: latest`, so every published version points
search engines at the current pages instead of competing with them.
A sitemap also cannot speak for URLs above its own location, so
`latest/sitemap.xml` can never cover the host. There is now a sitemap
index at the site root pointing at it, and robots.txt advertises that
index rather than the per-version file.
Finally, the failure mode itself is now a build error rather than
something a search console discovers weeks later: the deploy asserts
that the sitemap it is about to publish names saw.ndevuspace.com, and
fails loudly with the offending hosts if it does not.
Verified by building the way mike builds — `MIKE_DOCS_VERSION=latest`
gives canonical and sitemap entries under `/latest/`, and
`MIKE_DOCS_VERSION=0.6.2` declares `latest` canonical.
Refs #1473
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.
The site answered on a
github.ioaddress and told search engines nothing about itself beyond a title.Custom domain
site_urlmoves tosaw.ndevuspace.com, and the workflow writesCNAMEandrobots.txtinto the site root rather than shipping them fromdocs/. That distinction matters:mikepublishes each build into a version directory, so anything indocs/lands inlatest/— the wrong place for both files. Pages keeps the domain in repository settings for an Actions deployment; shipping the file as well is what stops a later deploy dropping it.Verified live before writing any of this:
cname: saw.ndevuspace.com,https_enforced: true, and DNS resolving to GitHub's Pages addresses.One defect worth calling out
site_urldeliberately carries thelatest/prefix. With the bare domain, the build emitted:…and a sitemap of 35 such URLs — none of which exist, because mike serves from
latest/, not the root. A sitemap of 404s is worse than no sitemap, andmkdocs build --strictcannot catch it because every link is internally valid. Fixed, and confirmed against a real build:A released version's pages now declare
latestcanonical, which consolidates ranking there rather than splitting it across every published version.Discoverability
A theme override adds Open Graph and Twitter card tags, so a shared link renders with a title, a summary and the project mark instead of a bare URL — plus one JSON-LD
SoftwareApplicationblock naming what this is, what it runs on, where to get it and its licence. Everything derives frommkdocs.yml, so there is no second copy to drift out of date.Verified against a real build, not by reading config
Installed the pinned docs toolchain and ran
mkdocs build --strict:latest/sitemap.xmlandsitemap.xml.gzgeneratedCNAMEand a validrobots.txt— its first draft used a heredoc that would have silently indented every line inside a YAMLrun:blockFollow-up worth knowing
Material's own build banner warns that MkDocs 2.0 rewrites the theming system and that all theme overrides will break. The override here is small and derives everything from config, so it should be cheap to port — but it is a known future cost, not a surprise.
Closes #1473