Wie Docsbook den Kopf einer Seite erstellt

Diese Seite beschreibt den Mechanismus: was Docsbook in <head> und in sitemap.xml für jede von ihm bereitgestellte Seite einfügt, und zwar in der Reihenfolge, in der der Code dies auflöst, damit Sie die Ausgabe vorhersehen können, anstatt sie mit curl abzurufen. Was das für Sie bedeutet und was Sie aktivieren müssen, erfahren Sie im SEO-Index.

Wie lautet der Titel auf der Seite, und woher stammt er?#

Der <title> einer Docsbook-Seite wird in drei Schritten ermittelt, wobei die erste Übereinstimmung gewinnt:

Reihenfolge	Quelle	Warum sie an erster Stelle steht
1	Frontmatter `title:`	Die einzige der drei Optionen, die du bearbeiten kannst, ohne zu ändern, was ein Leser auf der Seite sieht.
2	Der Textkörper `# H1`	Eine echte Überschrift, die bereits für einen Menschen geschrieben wurde.
3	Ein aus dem Dateinamen abgeleiteter Titel	Nie leer; eine Seite hat immer eine SERP-Zeile.

Der Arbeitsbereichsname wird dann genau einmal angehängt, als Page title — Workspace, und übersprungen, wenn der Titel ihn bereits als eigenständiges Wort enthält. "Docs" in "Docsbook" zählt nicht – beide Nachbarn der Übereinstimmung müssen Nichtwortzeichen sein, wobei dies anhand von Unicode-Buchstaben und -Ziffern statt ASCII-Zeichen geprüft wird, sodass ein kyrillischer oder CJK-Arbeitsbereichsname genauso wie ein lateinischer erkannt wird. Eine Seite, deren Titel nur aus dem Arbeitsbereichsnamen besteht (die Stammseite der Website), wird zu Workspace — Documentation. Die fertige Zeichenfolge wird als absoluter Titel ausgegeben, wodurch verhindert wird, dass die websiteweite %s | Docsbook-Vorlage eine zweite Kopie der Marke anhängt.

Auf einer übersetzten Seite stammt der Titel aus den zwischengespeicherten übersetzten Metadaten und andernfalls aus dem ersten <h1> des gespeicherten übersetzten HTML-Codes – eine chinesische Seite liefert also einen chinesischen Titel. Die Beschreibung bleibt dort bewusst in der Ausgangssprache: Docsbook erfindet dafür keine Übersetzung.

Was ist die Meta-Beschreibung, und was wird daraus entfernt?#

Reihenfolge: zuerst das Frontmatter description:, dann die eigenen einleitenden Absätze der Seite.

Bevor Fließtext zu einer Beschreibung werden kann, wird er bereinigt: HTML-Kommentare (also auch Widget-Markierungen), {icon-name}-Markierungen, Überschriften, Bilder, umzäunter und Inline-Code, Hervorhebungszeichen, rohe HTML-Tags, Aufzählungszeichen und Blockquote-Markierungen werden entfernt, und ein Markdown-Link wird auf seinen Linktext reduziert, statt seine URL in den Satz einzufügen. Absätze mit 20 Zeichen oder weniger werden als Fragmente verworfen.

Zwei Längen werden in einem Durchlauf aus derselben Quelle erstellt: 160 Zeichen für <meta name="description"> und 400 für og:description und das JSON-LD description. Eine im Frontmatter verfasste Beschreibung füllt beide. Die Kürzung endet an einer Wortgrenze und bevorzugt das Satzende, wenn dieses in die hintere Hälfte des verfügbaren Umfangs fällt; andernfalls endet der Text mit Auslassungspunkten.

Welche URL bezeichnet die Seite als kanonisch?#

Eine Seite, eine kanonische URL, in dieser Reihenfolge aufgelöst:

Ihre benutzerdefinierte Domain, sofern der Workspace über eine verfügt. Der *.docsbook.io-Mirror liefert dann Disallow: /, statt als zweite Kopie zu fungieren.
Ein dem Produkt zugehöriger Apex-Pfad für die eigene Dokumentation von Docsbook.
Der kurze Apex-Pfad für Showcase-Workspaces, da dies die URL ist, die 200 beantwortet — die Subdomain-Form leitet dorthin weiter.
https://<owner>.docsbook.io/<repo>/<path> für alles andere.

Übersetzte Seiten folgen denselben vier Zweigen, wobei die Locale dort eingefügt wird, wo der Router sie tatsächlich bereitstellt. en wird wieder auf die URL ohne Präfix zurückgeführt, da /en/page und /page byteidentischen Inhalt bereitstellen. Außerdem rendert eine Locale-URL für eine Seite, die nicht tatsächlich übersetzt ist, den Quelltext und verweist daher als kanonische URL auf die Quell-URL, statt zu behaupten, maßgeblich zu sein.

Welche Sprachen werden als Alternativen beworben?#

Das hreflang-Set enthält x-default und en an der Quell-URL sowie einen Eintrag für jede aktivierte Sprache, in die diese Seite tatsächlich übersetzt wurde. Das Aktivieren einer Sprache fügt sie nicht hinzu: Eine URL für eine nicht übersetzte Locale verweist per Canonical von sich weg, und ein einziges solches Mitglied reicht aus, um den gesamten Cluster ungültig zu machen. Eine Seite mit noindex erhält überhaupt kein Set statt eines verwaisten.

Die Sitemap gibt absichtlich keine seitenbezogenen Alternativen aus: Sie kann sich die seitenweise Übersetzungsprüfung nicht leisten. Daher würde jedes von ihr erstellte Set alle aktivierten Locales auflisten und genau den Widerspruch wieder einführen, den das seitenbezogene Set vermeiden soll.

Jede Seite gibt OpenGraph (og:title, og:description auf 400 Zeichen gekürzt, og:url = die kanonische URL, og:site_name, og:type: article, og:locale) und eine X-Karte des Typs summary_large_image mit der 160 Zeichen langen Beschreibung aus. Das Bild wird pro Seite mit 1200×630 generiert, 24 Stunden lang zwischengespeichert und rendert das Workspace-Logo, den Abschnitt als Eyebrow, den Seitentitel (auf 64 Zeichen gekürzt, bei mehr als 30 Zeichen kleiner gesetzt) und die auf 130 Zeichen gekürzte Beschreibung in den Farben des Workspace. Bei einer benutzerdefinierten Domain ist die Karte dasselbe Bild, das über eine absolute URL vom Apex angefordert wird – aber og:description enthält dort die 160 Zeichen lange Zeichenfolge und nicht die mit 400 Zeichen.

Welche Robots-Direktiven enthält eine Seite?#

Vier Regeln in strikter Reihenfolge ihrer Priorität:

Bedingung	Ausgegeben
Admin-Vorschau (`?preview=true`)	`noindex, follow`
Websiteweiter SEO-Schalter deaktiviert	`noindex, nofollow`
Frontmatter der Seite `noindex`	`noindex, follow`
Andernfalls	`index, follow`

noindex: true, noindex: yes, noindex: 1 und die Schreibweise robots: noindex zählen alle. Alles andere – nicht vorhanden, false, index – bedeutet Indexierung.

robots.txt unterscheidet sich je nach Host. Die Apex-Domain liefert eine großzügige Wildcard-Regel mit Crawl-delay: 10, verbietet die nicht inhaltlichen Pfade der App, nennt achtzehn KI- und Such-Crawler ausdrücklich unter Crawl-delay: 5, blockiert dreizehn Crawler mit hohem Volumen und geringem Zitierwert vollständig und führt eine Sitemap:-Zeile pro auffindbarer Website auf. Eine Workspace-Subdomain liefert dieselbe Bot-Richtlinie sowie eine eigene Sitemap:-Zeile. Eine benutzerdefinierte Domain liefert die Bot-Richtlinie ohne Sitemap:-Zeile – sie hat noch keine eigene Sitemap, und Crawler auf die Sitemap des Mirrors zu verweisen, würde für jede Seite einen zweiten Host bekannt machen. Crawl-Delay ist eine Höflichkeit, kein Standard: RFC 9309 definiert nur user-agent, allow und disallow, und Google fügt sitemap und nichts anderes hinzu – „andere Felder wie crawl-delay werden nicht unterstützt“.

Was kommt in sitemap.xml?#

Eine Sitemap pro Besitzer, höchstens stündlich neu erstellt. Für jedes indexierte Repository listet sie jede Markdown-Datei auf, wobei ein README im Repository-Stammverzeichnis dem Website-Stammverzeichnis zugeordnet wird und jede andere Datei ihrem eigenen Pfad. Jeder Eintrag enthält:

lastmod — das Datum des letzten Commits, der diese Datei verändert hat, aus dem Quell-Repository. Die Erstellungszeit wird nur verwendet, wenn die Commit-Historie nicht gelesen werden kann.
changefreq — weekly.
priority — 0.9 für eine Landingpage, 0.7 für eine Unterseite und 0.8 / 0.6 für deren Übersetzungen.

Übersetzte URLs werden nur dort aufgeführt, wo tatsächlich eine Übersetzung vorhanden ist, und doppelte URLs werden vor der Ausgabe der Datei zusammengeführt. Ein Repository, dessen Baum nicht gelesen werden kann, wird still verworfen, und der Rest der Sitemap wird weiterhin bereitgestellt: Eine Sitemap, die mit einem 500-Fehler abbricht, kostet mehr als eine, der eine Seite fehlt.

Seiten mit noindex werden weiterhin aufgeführt. Das Erkennen des Flags würde das Lesen des Inhalts jeder Seite erfordern, was der Aufbau der Sitemap bewusst nicht tut; die eigene Direktive der Seite wird beim Aufruf berücksichtigt, sodass die Kosten auf einen Crawl-Aufruf beschränkt bleiben.

Welche strukturierten Daten werden ausgegeben?#

Auf einem von Docsbook gehosteten Host gibt jede Seite ein JSON-LD @graph mit drei Knoten aus:

Organization — der Arbeitsbereich, seine URL, sein GitHub-Profil und sein Logo, falls festgelegt.
TechArticle — Überschrift, Beschreibung, kanonische URL, inLanguage, datePublished und dateModified aus der Commit-Historie des Quell-Repositorys, Autor, Herausgeber, mainEntityOfPage.
BreadcrumbList — Eigentümer → Website → jedes Pfadsegment, erstellt mit demselben kanonischen Builder, den <link rel="canonical"> verwendet, sodass kein Breadcrumb einen Host benennen kann, mit dem das kanonische Tag nicht übereinstimmt.

Wenn AEO aktiviert ist, wird speakable hinzugefügt, und FAQPage / HowTo-Knoten erscheinen nur, wenn die Seite tatsächlich diese Struktur enthält. Wenn GEO aktiviert ist, wird ein Person-Autor aus dem Frontmatter oder aus dem Autor des letzten Commits hinzugefügt.

Anker, Render-Modus und Hosts#

Anker. Überschriften-IDs stammen aus dem eigenen Slugger des Renderers, und jeder Deep-Link, den Docsbook ausgibt — Suchergebnisse, KI-Zitate — wird durch Aufruf derselben Bibliothek berechnet, statt die Zeichenfolge erneut herzuleiten. Doppelte Überschriften verweisen auf das erste Vorkommen.

Render-Modus. Eine anonyme Anfrage für eine öffentliche Seite wird aus einer zwischengespeicherten serverseitig gerenderten Route (24-Stunden-Fenster) ausgeliefert; Anfragen von angemeldeten Nutzern und Vorschauanfragen fallen auf ein dynamisches Rendering zurück und werden niemals im CDN zwischengespeichert. In beiden Fällen erhält der Crawler vollständiges HTML — kein clientseitiger Render-Schritt steht zwischen einem Bot und Ihrem Text.

Benutzerdefinierte Domain im Vergleich zur gemeinsamen Domain. Auf einer benutzerdefinierten Domain sind die kanonische URL, der Titel, die Beschreibung, Karten und ein TechArticle-Knoten vorhanden, und die Bot-Richtlinie wird durchgesetzt. Fünf Dinge fehlen: der SEO-Schalter für die gesamte Website und das seitenbezogene noindex (Seiten werden bedingungslos index, follow ausgeliefert), das hreflang-Set, die BreadcrumbList- und Organization-Knoten, Weiterleitungen für verschobene Seiten sowie die GEO-Signale — kein TL;DR-Block, keine sichtbare Aktualisiert-Zeile und ein TechArticle-Autor, der immer ein nach dem Repository-Eigentümer benanntes Person ist. Siehe Einschränkungen.

Warum diese Regeln (Belege)#

Regel	Warum sie für den Verbraucher funktioniert	Quelle
Ein `<title>` auf jeder Seite, Marke einmal angehängt	Google führt `<title>` an erster Stelle unter den Quellen für Titel-Links auf und warnt vor „wiederholtem oder standardisiertem Text in `<title>`-Elementen“	Titel-Links
Seitenspezifische Beschreibungen, niemals eine Zeichenfolge für die gesamte Website	„Identische oder ähnliche Beschreibungen auf jeder Seite einer Website sind nicht hilfreich“	Snippets
Canonical verweist auf eine URL, die den Status 200 zurückgibt, niemals auf eine Weiterleitung	`rel="canonical"` ist „ein starkes Signal“, und Google empfiehlt einen selbstreferenziellen Canonical auf der kanonischen Seite	Doppelte URLs zusammenführen
Nur tatsächlich übersetzte Sprachen in `hreflang`	„Wenn Seite X auf Seite Y verweist, muss Seite Y zurück auf Seite X verweisen … andernfalls werden diese Annotationen möglicherweise ignoriert“	Lokalisierte Versionen
Echte Commit-Daten als `lastmod`	Google verwendet `<lastmod>`, „wenn es konsistent und überprüfbar … korrekt ist“	Sitemap erstellen
Strukturierte Daten nur für Inhalte, die auf der Seite vorhanden sind	„Fügen Sie keine strukturierten Daten zu Informationen hinzu, die für den Nutzer nicht sichtbar sind“	Einführung in strukturierte Daten
Serverseitig gerendertes HTML statt clientseitigem	Google rendert JavaScript in einer Warteschlange, in der eine Seite „einige Sekunden … verbleiben kann, es aber länger dauern kann“, und „nicht alle Bots JavaScript ausführen können“	Grundlagen der JavaScript-SEO
1200×630-Kartenbild	„Verwenden Sie Bilder mit einer Größe von mindestens 1200 x 630 Pixeln“, nahe einem Verhältnis von 1,91:1	Bilder teilen

Grenzen und offene Fragen#

priority und changefreq dienen der Dekoration. Docsbook gibt sie aus, und Google stellt ausdrücklich fest: „Google ignoriert die Werte <priority> und <changefreq>.“ Das sitemaps.org-Protokoll ergänzt, dass die Priorität „die Position Ihrer URLs voraussichtlich nicht beeinflussen wird“. Sie kosten nichts und bringen Google nichts; bei anderen Suchmaschinen ist das unterschiedlich.
TechArticle steht nicht auf Googles Liste der Artikel-Rich-Ergebnisse. Es ist ein echter schema.org-Typ (Thing > CreativeWork > Article > TechArticle) und beschreibt den Inhalt zutreffend, aber Googles Article-Dokumentation besagt, dass Objekte „auf einem der folgenden schema.org-Typen basieren müssen: Article, NewsArticle, BlogPosting“. Betrachten Sie den Knoten als genaue Beschreibung, nicht als Berechtigung für ein Rich-Ergebnis. Auch strukturierte Daten sind nicht als Rankingfaktor dokumentiert: Googles Einführung beschreibt sie als Möglichkeit, eine Seite für eine erweiterte Darstellung zu qualifizieren, und sagt nichts über das Ranking aus.
Unklar ist, welchen Nutzen der 400 Zeichen lange og:description bringt. Docsbook erstellt ihn, weil das Tag Platz dafür bietet, wo <meta description> dies nicht tut. Keine von uns abgerufene Quelle dokumentiert, wie ein bestimmter Verbraucher og:description kürzt, und das OpenGraph-Protokoll legt keine Länge fest. Betrachten Sie 400 als hausinterne Entscheidung, nicht als gemessenes Optimum.
Seiten auf benutzerdefinierten Domains ignorieren Ihre Schalter für die Indexierung. Der Website-weite SEO-Schalter und das noindex pro Seite werden nur auf von Docsbook gehosteten Hosts berücksichtigt; auf einer benutzerdefinierten Domain wird die Seite unabhängig davon als index, follow ausgeliefert. /sitemap.xml wird dort ebenfalls nicht aufgelöst, daher enthält sein robots.txt keine Sitemap:-Zeile, und eine über Docsbook umbenannte Seite behält ihre Weiterleitung nur auf der gemeinsamen Domain. Um eine Seite heute auf einer benutzerdefinierten Domain aus dem Index herauszuhalten, lassen Sie sie aus dem veröffentlichten Repository heraus.
Eine einzelne Sitemap ist auf 50.000 URLs / 50 MB begrenzt, gemäß dem sitemaps.org-Protokoll und Googles eigener Begrenzung. Docsbook erstellt eine Sitemap pro Eigentümer und teilt sie nicht auf; ein Eigentümer, der diese Grenze überschreitet, wird derzeit nicht unterstützt.