Markdown generierte Webseiten

Nutzbar ab: Version 21

Die Ausgabe von Webseiten erfolgt in der Regel als HTML. Im Gegensatz zu Seitenbesuchern bevorzugen andere Besucher, wie z.B. Such- bzw. KI-Systeme eine schlanke, unformatierte Textform.

Weblication® kann dieselben Inhalte, die als HTML ausgeliefert werden, zusätzlich als Markdown bereitstellen. Inhalte werden einmal gepflegt, dann aber in zwei Ausgabeformaten bereitgestellt. Dieser Artikel zeigt, warum sich das lohnt und wie die Ausgabe samt passender Meta-Angabe im Head umgesetzt wird.

Allgemeines

Normalen Seitenbesuchern werden die Webseiten mit Navigation, Layout, Formatierungen, etc. angeboten. Die HTML-Seiten sollen ansprechend wirken. Dies ist für maschinelle Seitenbesucher (Bots, KI, etc.) nicht interessant, hier zählt der reine Inhalt. Bietet man diesen Besuchern die Seiten als Markdown an, ergeben sich mehrere Vorteile, u.a.:

  • Maschinenlesbarkeit
    Markdown ist klar strukturiert und ohne Ballast – ideal für Crawler, Feeds und LLM-basierte Systeme.
  •  Pflege für vielfältige Ausgabe
    Der Inhalt wird nur einmal gepflegt. HTML und Markdown entstehen aus denselben Daten.
  • Schlanke Übertragung
    Eine .md-Datei bzw. Markdown generierte Seite ist deutlich kleiner als das gerenderte HTML inklusive Markup.
  • Weiterverarbeitung
    Markdown lässt sich ohne Parser-Aufwand in Dokumentationen, Newslettern oder anderen Systemen weiterverwenden.
  • Zukunftssicherheit
    Der Trend zu textbasierten, „AI-freundlichen" Ausgabeformen hält an. Eine Markdown-Variante hält die Seite anschlussfähig. Kurz: Markdown kostet kaum Zusatzaufwand, macht die Inhalte aber für eine zweite, wachsende Zielgruppe nutzbar.

Aktivierung über Projektkonfiguration

Um MD-Versionen der Seiten zu erlauben, kann dies in aktueller BASE über die Projektkonfiguration aktiviert werden.

Projektkonfiguration: MD-Versionen erlauben
Projektkonfiguration: MD-Versionen erlauben

Beispiel: Auszug aus der Projektkonfiguration

...
  <headline text="KI Unterstützung"/>
  ...
  <variable description="MD-Versionen der Seiten erlauben" key="provide_version_md" type="char.yesno">yes</variable>
...

Umsetzung über pre.php und viewmode

Die Ausgabe wird über einen eigenen View-Modus gesteuert. Wird die Seite mit dem Parameter viewmode=md aufgerufen, liefert das System nicht das HTML, sondern den Inhalt als Markdown aus. Die Weiche dafür sitzt in der pre.php, die vor dem eigentlichen Rendering ausgeführt wird. Hier wird auch der korrekte Content-Type (text/markdown) gesetzt.
In der aktuellen BASE ist dies bereits im Standard umgesetzt und sieht auszugsweise wie folgt aus.
Sofern dies in älteren Projekten nachgerüstet werden soll, sollte dies am besten mit der aktuellen Auslieferung der pre.php abgeglichen werden.

Beispiel: Auszug aus der pre.php zu viewmode=md

// ...
  // Ansichtsmodus

  // ...
  else if(wRequest::getParameterSecure('viewmode') === 'md'){
    wEnv::setGlobalValue('wViewMode', 'md');
  }

  // ...

  // Falls die Anzeige als MD erlaubt sein soll
  $preVars['allowMD'] = wVariables::getValue('provide_version_md', '', $wPathLayout.'/wGlobal/content/variables/default.wVariables.php', 'wDoNotAddIfNoTemplate') == 'yes' ? true : false;

  // ...
  // ...

  }
  else if($preVars['allowMD'] && $preVars['viewMode'] == 'md'){
    $preResult = preg_replace('/(<body\b[^>]*>).*?(<main\b[^>]*>.*?<\/main>).*?(<\/body>)/is', '$1$2$3', $preResult, 1);
    $preResult = wStringconverter::convertHtmlToMarkdown($preResult);
    header('Content-Type: text/markdown; charset=utf-8');    
    print $preResult;
  }

  // ...

Meta-Link im Head

Damit die Markdown-Version gefunden wird, muss in der HTML-Seite auf sie verwiesen werden. Das erfolgt über das globale Head-Template htmlHead.wGlobal.php, das den Kopfbereich jeder Seite ausgibt.

Beispiel: Auszug aus der htmlHead.wGlobal.php

    
    <xsl:if test="php:functionString('wVariables::getValue', 'provide_version_md', $wGlobalProjectPath, '', 'wDoNotAddIfNoTemplate') = 'yes'">    
      <wsl:php>
        $wRequestURL        = '<xsl:value-of select="php:functionString('wStringconverter::maskApos', $wRequestURL)"/>';
        <![CDATA[
        print '<link rel="alternate" type="text/markdown" href="'.wEnv::getUrlHost().htmlspecialchars($wRequestURL, ENT_COMPAT).'?viewmode=md"/>';
        ]]>
      </wsl:php>
    </xsl:if>

Der href setzt sich aus der aktuellen Dokument-URL und dem viewmode-Parameter zusammen. So zeigt jede Seite automatisch auf ihre eigene Markdown-Variante – ohne dass pro Seite ein Pfad gepflegt werden muss.