Strukturierte Antworten

Docsbook schreibt ein <script type="application/ld+json">-Element pro Dokumentationsseite. Es enthält ein schema.org-@graph — ein einziges Array verknüpfter Objekte — statt mehrerer separater Script-Tags, sodass jedes Objekt auf der Seite denselben Kontext verwendet und über @id auf die anderen verweisen kann.

Auf dieser Seite wird genau aufgeführt, was in diesen Graphen einfließt, welche Bedingungen in deinem Markdown erfüllt sein müssen, damit die einzelnen Objekte erscheinen, und wie ein Fehler aussieht.

Was befindet sich im Graphen, und wodurch wird er aktiviert#

SoftwareApplication ist nicht Teil dieses Graphen. Docsbook gibt es auf seinen eigenen Marketingseiten aus, nicht in der Kundendokumentation — wenn Sie einen Wettbewerbsvergleich gelesen haben, der diesbezüglich etwas anderes über uns behauptet, befindet sich der Typ tatsächlich dort.

Datumsangaben stammen aus der Git-Historie der Datei, nicht aus dem Frontmatter: datePublished und dateModified werden aus dem neuesten Commit gelesen, der diese Datei verändert hat. Eine Seite ohne bisherige Commit-Historie enthält weder den einen noch den anderen Schlüssel, statt ein erfundenes Datum zu tragen.

Welche Markdown-Struktur erzeugt eine FAQPage?#

Ein Abschnitt wird zu Fragen, wenn eine der beiden Bedingungen erfüllt ist:

1. Eine H2-Überschrift, deren Text FAQ, Frequently asked questions oder dem russischen Частые вопросы / Вопросы и ответы / Часто задаваемые entspricht — ohne Berücksichtigung der Groß- und Kleinschreibung. Jede darunterliegende H3-Überschrift wird zu einer Frage, unabhängig davon, ob sie mit einem Fragezeichen endet.
2. Jede H3-Überschrift, die mit ? endet, überall im Dokument, unabhängig davon, in welchem Abschnitt sie sich befindet.

Die Antwort umfasst jede nicht leere Zeile zwischen dieser H3-Überschrift und der nächsten Überschrift. Inline-*, _ und Backtick-Zeichen werden entfernt. Inhalts-Widget-Markierungen (<!-- widget:accordion --> und ihre schließende Markierung) werden übersprungen, statt in die Antwort aufgenommen zu werden, da ein Akkordeon die übliche Art ist, eine FAQ zu verfassen.

Anschließend werden die Begrenzungen in dieser Reihenfolge angewendet: Ein abschließendes ? wird an jede Frage angehängt, der ein solches fehlt; jede Antwort wird auf 1.000 Zeichen gekürzt; ein Paar wird verworfen, wenn die Frage höchstens 3 Zeichen oder die Antwort höchstens 10 Zeichen umfasst; und die Seite enthält höchstens 20 Fragen.

## FAQ
 
### Does a custom domain change my page URLs
 
Yes. Every canonical URL, sitemap entry and breadcrumb item moves to the new host on the next render.
 
### How long does the certificate take
 
Usually under a minute after the CNAME resolves.

Eine H3-Überschrift, die keine Frage ist und sich nicht in einem FAQ-Abschnitt befindet, erzeugt nichts. ### Install the CLI unter ## Setup wird korrekt ignoriert.

Welche Markdown-Struktur erzeugt ein HowTo?#

Drei Bedingungen müssen gleichzeitig erfüllt sein:

1. Eine H1, H2 oder H3, die mit How to beginnt — oder das russische Как, wobei das nächste Zeichen kein Buchstabe oder keine Ziffer sein darf, sodass Каким образом nicht übereinstimmt.
2. Darauf folgt eine nummerierte Liste — sowohl 1. als auch 1) zählen.
3. Die Liste enthält mindestens 3 Schritte.

Jeder nummerierte Eintrag wird zu einem HowToStep. Sein name ist der erste Satz, der an einer Wortgrenze auf 80 Zeichen gekürzt und mit einer Auslassung versehen wird; sein text ist der gesamte Eintrag, begrenzt auf 1.000 Zeichen. Links werden auf ihren Ankertext reduziert und Inline-Hervorhebungen entfernt. Inhalte innerhalb von eingerückten Codeblöcken werden vollständig ignoriert, sodass eine nummerierte Liste in einem Beispiel nicht zu einer Prozedur wird.

Eine Prozedur ist auf 20 Schritte und eine Seite auf 5 HowTo-Objekte begrenzt.

Ein Stepper-Widget zählt als nummerierte Liste. Innerhalb eines <!-- widget:stepper -->-Bereichs eröffnet jede Überschrift den nächsten Schritt, unabhängig von ihrer Ebene — der Bereich wird jedoch nur dann zu einem HowTo, wenn eine How to / Как-Überschrift ihn eingeführt hat. Ein Stepper unter # Quick start erzeugt nichts.

## How to move your docs to a custom domain
 
1. Open the admin panel and select **Custom Domain**.
2. Enter `docs.example.com` and save.
3. Add the CNAME record the panel shows to your DNS provider.

Zwei Schritte erzeugen nichts. Wenn die Prozedur tatsächlich zwei Schritte umfasst, ist das das korrekte Ergebnis — fügen Sie der Liste keine zusätzlichen Einträge hinzu, um den Schwellenwert zu erreichen.

So sieht das tatsächlich ausgegebene JSON-LD aus#

Dies ist die Ausgabe der eigenen Extraktoren von Docsbook, ausgeführt über die beiden oben genannten Markdown-Blöcke:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Does a custom domain change my page URLs?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes. Every canonical URL, sitemap entry and breadcrumb item moves to the new host on the next render."
          }
        },
        {
          "@type": "Question",
          "name": "How long does the certificate take?",
          "acceptedAnswer": { "@type": "Answer", "text": "Usually under a minute after the CNAME resolves." }
        }
      ]
    },
    {
      "@type": "HowTo",
      "name": "How to move your docs to a custom domain",
      "step": [
        { "@type": "HowToStep", "position": 1, "name": "Open the admin panel and select Custom Domain.", "text": "Open the admin panel and select Custom Domain." },
        { "@type": "HowToStep", "position": 2, "name": "Enter docs.example.com and save.", "text": "Enter docs.example.com and save." },
        { "@type": "HowToStep", "position": 3, "name": "Add the CNAME record the panel shows to your DNS provider.", "text": "Add the CNAME record the panel shows to your DNS provider." }
      ]
    }
  ]
}

Beachte, was der Extraktor mit den Überschriften der Fragen gemacht hat: Er hat ? angehängt, das im Markdown ausgelassen wurde. Deshalb liest sich eine als Frage formulierte H3 im Markup korrekt, selbst wenn du sie als Aussage verfasst hast.

Inhalt des Breadcrumb-Pfads#

Der Pfad besteht aus der Startseite des Arbeitsbereichs → der Startseite des Projekts → einem Element pro Pfadsegment. Der name jedes Segments wird in eine menschenlesbare Form gebracht – die Erweiterung .md wird entfernt, Bindestriche und Unterstriche werden in Leerzeichen umgewandelt und jedes Wort wird großgeschrieben –, während seine item-URL mit demselben Builder für kanonische URLs erstellt wird, den auch <link rel="canonical"> der Seite verwendet, sodass die beiden niemals unterschiedliche Hosts benennen können. In einer übersetzten Spracheinstellung werden die URLs des Pfads innerhalb dieser Spracheinstellung ausgedrückt.

{
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "acme", "item": "https://acme.docsbook.io" },
    { "@type": "ListItem", "position": 2, "name": "Acme Handbook", "item": "https://acme.docsbook.io/handbook" },
    { "@type": "ListItem", "position": 3, "name": "Guides", "item": "https://acme.docsbook.io/handbook/guides" },
    { "@type": "ListItem", "position": 4, "name": "Custom Domains", "item": "https://acme.docsbook.io/handbook/guides/custom-domains" }
  ]
}

Google verlangt position, name und item für jedes ListItem sowie mindestens zwei Elemente in der Liste (Google, Breadcrumb); eine Seite im Stammverzeichnis des Projekts erzeugt genau die beiden Startseiten-Elemente, was dem dokumentierten Minimum entspricht.

Was speakable aussagt#

Wenn AEO aktiviert ist, erhält TechArticle:

"speakable": {
  "@type": "SpeakableSpecification",
  "cssSelector": [".tldr", "article > p:first-of-type", "h1"]
}

schema.org definiert SpeakableSpecification als Kennzeichnung für „Abschnitte eines Dokuments, die als besonders gut vorlesbar hervorgehoben sind“ (schema.org). Die Selektorliste gibt eine Präferenzreihenfolge an: den GEO-TL;DR-Block, wenn GEO aktiviert ist, dann den ersten Absatz des Artikels und anschließend die H1. Die praktische Konsequenz ist, dass das, was ein Leser zuerst sieht, auch das ist, was eine Maschine als Zusammenfassung behandelt – eine Seite, die mit Hintergrundinformationen statt mit einer Antwort beginnt, deklariert den Hintergrund als ihre Zusammenfassung.

Was passiert, wenn die Auszeichnung fehlerhaft ist#

Docsbook validiert den Graphen nicht, bevor er ausgeliefert wird. Im Rendering-Pfad gibt es keinen Schema-Linter, und audit_geo — das Tool, das den Crawler-Zugriff, serverseitiges Rendering und llms.txt überprüft — untersucht JSON-LD überhaupt nicht. Was die Extraktoren erzeugt haben, landet auf der Seite. Vier Fehlerszenarien sollte man kennen:

• Der Detektor hat nichts gefunden. Das häufigste und am wenigsten sichtbare Ergebnis: AEO ist aktiviert, die Seite enthält einen FAQ-ähnlichen Abschnitt, und kein FAQPage erscheint. Fast immer liegt es an der Überschriftenebene — der Detektor liest H2-Abschnitte und H3-Fragen, sodass eine FAQ mit H3-Abschnitten und H4-Fragen nichts ergibt.
• Der Detektor hat zu viel gefunden. Jede H3-Überschrift, die mit ? endet, wird überall im Dokument zu einer FAQ-Frage, auch eine rhetorische Überschrift im Fließtext. Das Ergebnis ist eine gültige Auszeichnung, die eine Seite beschreibt, bei der es sich nicht um eine FAQ handelt. Das ist ein Richtlinienproblem und kein Syntaxproblem — gemäß den Richtlinien von Google muss „Ihre strukturierten Daten eine wahrheitsgetreue Darstellung des Seiteninhalts sein“ (Google). Formuliere die Überschrift als Aussage um, dann wird sie nicht mehr erkannt.
• Rohes HTML in einer Antwort führt zum Abbruch des Blocks. Der Antworttext wird unverändert in das JSON kopiert. Eine wörtliche </script>-Sequenz innerhalb einer FAQ-Antwort beendet das JSON-LD-Element vorzeitig, und jedes Objekt danach geht verloren. Halte rohes HTML aus FAQ-Antworten heraus; verwende das Markdown, das auch der Rest der Seite nutzt.
• Die Seite wird über eine benutzerdefinierte Domain ausgeliefert. Ein Workspace unter einer eigenen Domain wird über einen anderen Pfad gerendert, der ein einfaches TechArticle und nichts weiter ausgibt — keine Breadcrumb, kein FAQPage, kein HowTo, kein speakable. Überprüfe die *.docsbook.io-Adresse, bevor du zu dem Schluss kommst, dass der Detektor fehlgeschlagen ist.

Überprüfe die Seite mit Googles Rich Results Test oder dem Schema Markup Validator. Beachte, was ein grünes Ergebnis heute bedeutet und was nicht: BreadcrumbList wird weiterhin als Rich Result unterstützt, während FAQPage und HowTo zwar gültiges schema.org sind, von Google aber nicht mehr gerendert werden — siehe die Einschränkungen von AEO.

Grenzen und offene Fragen#

• TechArticle ist keiner der drei Typen, die Google für das Rich Result „Artikel“ nennt. In der Google-Dokumentation steht: „Artikelobjekte müssen auf einem der folgenden schema.org-Typen basieren: Article, NewsArticle, BlogPosting“ (Google, Artikel). TechArticle ist ein schema.org-Untertyp von Article – „Ein technischer Artikel – Beispiel: How-to-(Aufgaben-)Themen, Schritt-für-Schritt-Anleitungen, prozedurale Fehlerbehebung, Spezifikationen“ (schema.org) – und die zutreffende Beschreibung einer Dokumentationsseite. Ob Google einen Untertyp als für das Rich Result „Artikel“ zulässig behandelt, wird in dieser Dokumentation ebenfalls nicht eindeutig angegeben. Wir haben uns für Genauigkeit statt für Vermutungen entschieden.
• Die FAQ- und How-to-Erkenner erkennen nur Englisch und Russisch. Die Abschnittsüberschriften und das Verfahrensverb werden mit diesen beiden Sprachen abgeglichen. Eine deutsche oder japanische FAQ-Seite erzeugt kein FAQPage, es sei denn, ihre H3-Überschriften enden mit ?.
• Antworten bestehen ausschließlich aus Fließtext. Alles zwischen einer Frageüberschrift und der nächsten Überschrift wird zusammengefügt und bei 1.000 Zeichen abgeschnitten – Tabellen, Codeblöcke und Bilder landen als ihre Rohquelle im Antworttext oder werden mitten im Inhalt abgeschnitten. Beschränken Sie FAQ-Antworten auf wenige Sätze.
• Es wird nirgends angegeben, wie viel ausgegeben wurde. Es gibt kein Panel, Protokoll oder keine API, die Ihnen mitteilt, wie viele FAQPage-Fragen oder HowTo-Objekte eine bestimmte Seite erzeugt hat. Sehen Sie sich den Quelltext an oder verwenden Sie einen Validator.

Verwandte Themen#

• AEO — was eine Antwortmaschine benötigt und was das Markup noch bewirken kann
• Inhaltsregeln für Antwortmaschinen — die Textregeln, die entscheiden, ob die Passage ausgewählt wird
• GEO — der TL;DR-Block, den der Selektor speakable bevorzugt
• SEO — Meta-Tags, Sitemap und kanonische URLs
• Inhalts-Widgets — die Stepper- und Akkordeonbereiche, die die Detektoren verstehen