Repository navigation
docs: publish a developer guide on GitHub Pages and optimize for search - #30
Merged
Merged
Conversation
The repository explained itself only through the README, which meant the one thing it exists to teach — how to write a Speculum plugin — was not reachable from a search engine, and link previews of it were bare. Adds a four-page static site under docs/, built on the same stylesheet as the Speculum documentation so the two read as one project: - index.html what a plugin is and how the host discovers one - quickstart.html the released JAR or a source build, then deployment - module-anatomy.html every file in the project and what the host does with it - settings-schema.html declaring options the admin console renders Search-engine groundwork on every page: a unique title and meta description, a canonical link, Open Graph and Twitter Card tags pointing at a generated 1200x630 card, and one h1. index.html also carries JSON-LD describing the project as SoftwareSourceCode plus the guide as a TechArticle. robots.txt and sitemap.xml cover all four pages, and .nojekyll keeps Pages from reprocessing the output. The README now links the guide instead of growing further.
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.
Problem
This repository exists to teach one thing — how to write a Speculum plugin — and that explanation lived only in the README. Nothing was indexable as a guide, there was no page to link anyone to, and sharing the repo produced a bare link preview.
Change
A four-page static site under
docs/, built on the same stylesheet as the Speculum documentation so the two read as one project.index.htmlquickstart.htmlmirror-apiversionmodule-anatomy.htmlServiceLoadermanifest,ModuleFactory, the lifecycle hooks, ComposeContent(), the notification bus, the thin-JAR Gradle setupsettings-schema.htmlsettingsSchema()end to end: the eight types,defaultvs.defaultConfig(),advanced, preview templates, and how to test a schemaThe guide documents the real behaviour of this module and of
mirror-api1.3.0, including the traps worth naming — a typo inMETA-INF/servicesfails silently,compileOnlydependencies do not reach the test classpath, and a spec'sdefaultlies if it drifts from what the module code actually falls back to.Search-engine groundwork
Every page carries a unique
<title>and meta description, a canonical link, Open Graph and Twitter Card tags, and exactly one<h1>.index.htmladds JSON-LD describing the project asSoftwareSourceCodeand the guide as aTechArticle.robots.txtpoints at asitemap.xmlcovering all four pages, and.nojekyllstops Pages reprocessing the output.The 1200×630 Open Graph card is generated rather than borrowed, so previews say Example Module instead of showing Speculum's own artwork.
README
Now links the guide at the top and in a Documentation table, instead of growing further.
Verification
A validator over all four pages checks: balanced tags with nothing left unclosed, every required SEO tag present, exactly one
<h1>, parseable JSON-LD, every<img>carryingalt, every internal link and every#fragmentresolving to a real target, and the sitemap being well-formed and matching the page set. All four pass.Rendered locally and reviewed at desktop and 390px: nav, cards, tables and code blocks all behave, and the mobile hamburger works.
After merge
Pages still has to be switched on for this repository —
main, folder/docs. The site will be at https://pierrejochem.github.io/SpeculumExampleModule/.