Code / Terminal · FWT Dokumentation

Inhalt / Code

Code, Terminal und technische Inhalte

FWT wird auch für Dokumentationen, Anleitungen, Webtools und technische Projektseiten genutzt. Dafür braucht es saubere Darstellungen für Code, Befehle, Dateipfade, Terminalausgaben und technische Hinweise.

Diese Bausteine sind kein kompletter Syntax-Highlighter. Sie sorgen aber dafür, dass technische Inhalte gut lesbar, klar abgegrenzt und optisch hochwertig dargestellt werden.

Wichtig: Codebeispiele müssen verständlich sein. Hübsche Darstellung ersetzt keine klare Erklärung.

Inline

Inline-Code und Tastaturhinweise

Inline-Code eignet sich für Klassennamen, Dateinamen oder kurze technische Begriffe im Fließtext. Tastaturhinweise werden mit kbd dargestellt.

Live-Beispiel

Nutze fwt-container für normale Inhaltsbreiten.

Seite hart neu laden: Strg + F5

HTML-Code anzeigen

<p class="fwt-text">
    Nutze <code class="fwt-code-inline">fwt-container</code> für normale Inhaltsbreiten.
</p>

<p class="fwt-text">
    Seite hart neu laden:
    <kbd class="fwt-kbd">Strg</kbd> + <kbd class="fwt-kbd">F5</kbd>
</p>

Inline-Code sollte kurz bleiben. Für längere Beispiele ist ein Codeblock besser.

Codezeile

Codezeilen mit Nummer

Einzelne Codezeilen mit Nummer eignen sich für kurze Hinweise, einzelne Klassen oder kurze Anleitungsstellen.

Live-Beispiel

01 <div class="fwt-frame">Inhalt</div>

02 Cache-Version nach CSS-Änderungen erhöhen.

03 Pfad prüfen, wenn eine Datei nicht geladen wird.

HTML-Code anzeigen

<div class="fwt-code-line fwt-code-line-primary">
    <span class="fwt-code-number">01</span>
    <code>&lt;div class="fwt-frame"&gt;Inhalt&lt;/div&gt;</code>
</div>

<div class="fwt-code-line fwt-code-line-warning">
    <span class="fwt-code-number">02</span>
    <code>Cache-Version nach CSS-Änderungen erhöhen.</code>
</div>

<div class="fwt-code-line fwt-code-line-danger">
    <span class="fwt-code-number">03</span>
    <code>Pfad prüfen, wenn eine Datei nicht geladen wird.</code>
</div>

Codeblock

Größere Codeblöcke

Codeblöcke eignen sich für HTML, CSS, PHP, JavaScript oder andere längere Beispiele. Die Kopfzeile kann Titel und Sprache anzeigen.

Live-Beispiel

Einfaches HTML-Beispiel HTML

<section class="fwt-section">
    <div class="fwt-container">
        <h2 class="fwt-h2">Überschrift</h2>
        <p class="fwt-text">Ein kurzer Beispieltext.</p>
    </div>
</section>

HTML-Code anzeigen

<div class="fwt-code-block">
    <div class="fwt-code-header">
        <span class="fwt-code-title">Einfaches HTML-Beispiel</span>
        <span class="fwt-code-language">HTML</span>
    </div>

    <pre class="fwt-code-pre"><code>&lt;section class="fwt-section"&gt;
    &lt;div class="fwt-container"&gt;
        &lt;h2 class="fwt-h2"&gt;Überschrift&lt;/h2&gt;
        &lt;p class="fwt-text"&gt;Ein kurzer Beispieltext.&lt;/p&gt;
    &lt;/div&gt;
&lt;/section&gt;</code></pre>
</div>

Für Release II kann hier später eine erweiterte Copy-Funktion oder ein echter Syntax-Highlighter ergänzt werden.

Terminal

Terminalblöcke

Terminalblöcke eignen sich für Serverbefehle, Installationsschritte, Prüfungen oder Konsolenausgaben.

Live-Beispiel

Terminal

christian@server:~$ cd /var/www/projekte/webtools/fwt
christian@server:~/fwt$ ls public/assets/css
# CSS-Dateien prüfen

HTML-Code anzeigen

<div class="fwt-terminal">
    <div class="fwt-terminal-top">
        <span class="fwt-terminal-dot fwt-terminal-dot-danger"></span>
        <span class="fwt-terminal-dot fwt-terminal-dot-warning"></span>
        <span class="fwt-terminal-dot fwt-terminal-dot-success"></span>
        <span class="fwt-terminal-title">Terminal</span>
    </div>

    <pre class="fwt-terminal-body"><span class="fwt-terminal-prompt">christian@server</span>:~$ cd /var/www/projekte/webtools/fwt
<span class="fwt-terminal-prompt">christian@server</span>:~/fwt$ ls public/assets/css
<span class="fwt-terminal-comment"># CSS-Dateien prüfen</span></pre>
</div>

Befehle sollten nicht blind kopiert werden. In der Doku muss klar sein, was ein Befehl bewirkt.

Pfade / Befehle

Dateipfade und kurze Befehle

Dateipfade und einzelne Befehle sollen sich deutlich vom normalen Text abheben, ohne gleich einen großen Codeblock zu brauchen.

Live-Beispiel

Datei: public/assets/css/03-content/code.css

Befehl: grep -R "fwt-code" public/assets/css -n

HTML-Code anzeigen

<p class="fwt-text">
    Datei:
    <span class="fwt-path">public/assets/css/03-content/code.css</span>
</p>

<p class="fwt-text">
    Befehl:
    <span class="fwt-command">grep -R "fwt-code" public/assets/css -n</span>
</p>

Ausgabe

Ausgabe- und Ergebnisblöcke

Ergebnisblöcke eignen sich für Prüfmeldungen, Diagnoseausgaben, Statusmeldungen oder kurze technische Resultate.

Live-Beispiel

OK: Datei wurde gefunden. OK: CSS wurde eingebunden. OK: Doku-Seite ist erreichbar.

Hinweis: Cache-Version prüfen, wenn Änderungen nicht sichtbar sind.

Fehler: Datei public/assets/css/03-content/code.css wurde nicht geladen.

HTML-Code anzeigen

<div class="fwt-code-output fwt-code-output-success">OK: Datei wurde gefunden.
OK: CSS wurde eingebunden.
OK: Doku-Seite ist erreichbar.</div>

<div class="fwt-code-output fwt-code-output-warning">Hinweis: Cache-Version prüfen, wenn Änderungen nicht sichtbar sind.</div>

<div class="fwt-code-output fwt-code-output-danger">Fehler: Datei public/assets/css/03-content/code.css wurde nicht geladen.</div>

Ausgabe-Blöcke sollten keine geheimen Daten enthalten. Passwörter, Tokens und Zugangsdaten gehören nicht in sichtbare Beispiele.

Hinweise

Technische Hinweisboxen

Technische Hinweisboxen helfen, wichtige Zusatzinformationen in Anleitungen oder Dokumentationen sichtbar zu machen.

Live-Beispiel

Technischer Hinweis

Diese Box eignet sich für kurze technische Erklärungen innerhalb einer Anleitung.

Achtung

Nach Änderungen an CSS-Dateien sollte die Cache-Version erhöht werden.

Fehler vermeiden

Keine echten Passwörter, Tokens oder Zugangsdaten in Beispielen anzeigen.

HTML-Code anzeigen

<div class="fwt-tech-note">
    <h3 class="fwt-tech-note-title">Technischer Hinweis</h3>
    <p class="fwt-tech-note-text">
        Diese Box eignet sich für kurze technische Erklärungen innerhalb einer Anleitung.
    </p>
</div>

<div class="fwt-tech-note fwt-tech-note-warning">
    <h3 class="fwt-tech-note-title">Achtung</h3>
    <p class="fwt-tech-note-text">
        Nach Änderungen an CSS-Dateien sollte die Cache-Version erhöht werden.
    </p>
</div>

<div class="fwt-tech-note fwt-tech-note-danger">
    <h3 class="fwt-tech-note-title">Fehler vermeiden</h3>
    <p class="fwt-tech-note-text">
        Keine echten Passwörter, Tokens oder Zugangsdaten in Beispielen anzeigen.
    </p>
</div>

Barrierefreiheit

Code verständlich darstellen

Code nicht nur farbig erklären

Farben können helfen, aber die Erklärung muss im Text stehen.

<div class="fwt-code-output-warning">Hinweis...</div>

Lange Zeilen scrollbar halten

Code darf das Layout nicht sprengen. Horizontales Scrollen ist bei Codeblöcken oft sinnvoller als automatischer Umbruch.

<pre class="fwt-code-pre"><code>...</code></pre>

Keine echten Zugangsdaten

Beispiele dürfen keine echten Passwörter, Tokens oder privaten Pfade enthalten.

password=BEISPIEL_NICHT_ECHT

Befehle erklären

Besonders Terminalbefehle sollten kurz erklären, was sie tun.

<span class="fwt-command">ls public/assets/css</span>

Sprache kennzeichnen

Bei größeren Codeblöcken hilft eine sichtbare Sprachangabe.

<span class="fwt-code-language">HTML</span>

Copy-Funktion später erweitern

Für Release II kann das Kopieren von Codeblöcken komfortabler werden.

Release II: Copy-Code erweitern