Software- und Codedokumentation

Das Content-Modell von Paligo bietet sehr gute Unterstützung für die Dokumentation von Software und Codefragmenten. Zum Markieren von UI-Elementen und Code-Elementen können Sie verschiedene Elemente einsetzen. Die am häufigsten verwendeten werden unter Allgemeine Softwareelemente beschrieben. Eine vollständige Auflistung der verfügbaren Elemente finden Sie im Standard-Elementverzeichnis von DocBook.

Hier ein Beispiel mit einen Codeblock, wie er in der veröffentlichten Ausgabe erscheint. Dieser Codeblock enthält Anmerkungen.

In Ihrem Paligo-Content können Sie Folgendes hinzufügen:

Codeblöcke für mehrzeilige Codebeispiele
Anmerkungenzum Hinzufügen von „Hotspots“ zu Teilen eines Codeblocks, zu denen Erläuterungen verlinkt sind.
Inline-Code-Elemente für den Fall, dass Sie kleinere Code-Abschnitte in einen Absatz einfügen möchten.

Sie können auch Code aus einer externen Quelle einbetten, einschließlich Swagger OpenAPI einbetten. Auch Swagger OpenAPI importieren in Paligo ist möglich. Bei einem Import befinden sich die Inhalte genau wie Ihre anderen Inhalte in Paligo. Dies unterscheidet sich vom Einbetten von Inhalten, bei dem die Inhalte erst während des Veröffentlichungsprozesses und nur für die veröffentlichte Ausgabe in ein Paligo Topic eingefügt werden.

Für Publikationen steht auch das HTML5 API-Layout zur Verfügung, das speziell für die Dokumentation von APIs entwickelt wurde. Das Layout umfasst drei Panels: für Navigation auf der linken Seite, für Inhalte in der Mitte und für Codebeispiele auf der rechten Seite, außerdem Sprachregisterkarten zum Umschalten zwischen Beispielen in verschiedenen Programmiersprachen, siehe

Tipp

Siehe auch Elemente für die Dokumentation von Software und Codes.

Allgemeine Softwareelemente

Auch wenn Sie kaum Code dokumentieren, müssen Sie bei der Dokumentation von Software häufig auf Teile des Softwareprodukts verweisen, wie z. B. UI-Komponenten, Dateinamen, Tags, Tastaturkürzel usw. Hier sind einige gängige Elemente, die verwendet werden können:

Beispiel 1. UI-Komponenten

Die einfachste Art, auf UI-Komponenten (Schaltflächen, Menüs, Symbolleisten usw.) zu verweisen, ist die Verwendung eines Elements als generisches UI-Element: guilabel. Hier ein Beispiel:

Klicken Sie auf die Schaltfläche OK.

Da dies so weit verbreitet ist (und empfohlene Praxis, statt solche Begriffe fett oder kursiv hervorzuheben), gibt es auch ein Tastaturkürzel dafür: AltG.

Wenn Sie differenzierter vorgehen möchten, können Sie stattdessen die Elemente noch spezifischer verwenden, z. B. guilabel nur für Etiketts, guibutton für Schaltflächen, guimenu und dessen Unterelemente für Menüs usw.

Ein häufiger Arbeitsschritt ist die Erstellung von Dateinamen und -pfaden: Hierfür kommt das Element filename zum Einsatz.

Beispiel 2. Tastaturkürzel

Für das richtige Erstellen von Tastaturkürzeln, entweder sofort oder im späteren Verlauf Ihrer Arbeit, sowie deren unterschiedliche Ausgestaltung für verschiedene Ausgaben verwenden Sie das keycap-Element:

Drücken Sie AltK, um ein keycap-Element hinzuzufügen.

Wie Sie sehen, kann dieses Element gestaltet werden – hier als Tasten der Tastatur. Im vorliegenden Beispiel verfügt dieses Element selbst über ein Tastaturkürzel, um die Bedienung zu erleichtern.

Wenn Sie möchten, können Sie es einzeln oder in Kombination mit dem keycombo-Element verwenden. Wenn keycap-Elemente in ein keycombo-Element eingebettet sind, wird standardmäßig ein „+“-Symbol zwischen den Tasten ausgegeben (was bei Bedarf in Stylesheets angepasst werden kann).

Codeblöcke in Ihren Inhalten

Zu den häufigsten Anforderungen bei der Dokumentation von Software zählt das Schreiben von Codeblöcken. Das wichtigste Element hierfür ist programlisting.

So fügen Sie ein programlisting-Element hinzu:

Positionieren Sie den Cursor am Anfang der Zeile, in die der Codeblock eingefügt werden soll.
Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.
Suchen Sie das programlisting-Element und wählen Sie es aus.

Sobald Sie ein programlisting-Element hinzufügen, erscheint ein Codefragment-Feld im Topic.
Fügen Sie Ihren Code in das Codefragment-Feld ein.

Das programlisting-Element wird manchmal als „verbatim“ bezeichnet, da der in das Element eingefügte Code exakt so dargestellt wird, wie er im Editor erscheint. Beispielsweise werden Leerzeichen und Zeilenumbrüche beibehalten, um den Code korrekt darzustellen. Einige andere Elemente funktionieren genauso, wie z. B. screen oder literallayout.

Beispiel 3. Ein programlisting-Beispiel

Hier wurde eine Javascript-Funktion innerhalb eines programlisting-Elements hinzugefügt. So sieht der Code in der Ausgabe aus.

function myFunction() { 1
    var x = "", i;
    for (i=0; i<5; i++) {
        x = x + "The number is " + i + "<br>";
    }
    document.getElementById("demo").innerHTML = x; 2
}

1	Dies ist eine Javascript-Funktion
2	Hiermit wird ein Wert für ein Element mithilfe des DOM-Modells festgelegt.

In dem gezeigten Beispiel wird ein Codeblock innerhalb des programlisting-Elements hinzugefügt. Die Javascript-Funktion enthält (1) in der ersten Zeile und (2) in der letzten Zeile. Hierbei handelt es sich um Callouts, mit denen Sie Anmerkungen erstellen können.

Anmerkungen zu Codeblöcken erstellen

Mithilfe des Elements calloutlist und von co-Elementen können Sie Anmerkungen erstellen. In der veröffentlichten Ausgabe fungieren die Callouts als anklickbare „Hotspots“, mit denen sich Teile des Codes hervorheben lassen. Klickt man auf einen „Hotspot“, gelangt man zum Callout-Erklärtext für diesen „Hotspot“.

Beispielsweise besitzt das Codebeispiel in der nachstehenden Abbildung zwei Callout-„Hotspots“, die mit 1 und 2 bezeichnet sind. Unterhalb des Codebeispiels befinden sich Ziffern, die den Hotspots entsprechen, und neben jeder Ziffer steht eine Anmerkung, die über den Zweck des entsprechenden Codeabschnitts aufklärt.

A code sample. In the code, there are callout icons labelled 1 and 2. Below the code, there are matching 1 and 2 callout icons, each with a text description of the corresponding line of code.

So erstellen Sie Anmerkungen mit calloutlist:

Wählen Sie eine Position im Codeblock, an die ein Callout-„Hotspot“ gesetzt werden soll.
Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.
Wählen Sie das co-Element aus und geben Sie ihm im Abschnitt Elementattribute einen xml:id-Wert. Jedes co-Element muss einen xml:id-Wert besitzen, der in diesem spezifischen Topic eindeutig ist. Zum Beispiel können Sie dem ersten co-Element die xml:id id_1, dem zweiten co-Element die xml:id id_2 und so weiter geben.
Fügen Sie hinter dem programlisting-Element, das Ihren Codeblock enthält, ein calloutlist-Element hinzu.

Tipp

Meist empfiehlt es sich, die programlisting- und calloutlist-Elemente in ein example-Element einzufügen, so dass sie sich alle in einem gemeinsamen „Container“ (dem example-Element) befinden.
Weisen Sie außerdem jedem callout in der calloutlist eine xml:id zu, die sich von denen in den co-Elementen unterscheidet, z. B. „callout_1“, „callout_2“ usw. Auch diese IDs müssen eindeutig sein.
Verknüpfen Sie die co-Elemente mit den callout-Elementen:
1. Fügen Sie für jedes co-Element ein linkends-Attribut hinzu. Stellen Sie den Wert des linkends-Attributs auf den xml:id-Wert von callout ein, mit dem Sie es verknüpfen möchten.
2. Fügen Sie für jedes callout-Element das Attribut arearefs hinzu. Geben Sie als Wert des arearefs-Attributs den xml:id-Wert des co-Elements ein, mit dem es verknüpft werden soll.

Code in einem Absatz (Inline-Code)

Wenn Sie in einen Absatz statt eines vollständigen Codeblocks ein kleines Codefragment einfügen möchten, verwenden Sie ein Inline-Element. Für diesen Zweck bieten sich mehrere Elemente an, wobei code hier vielleicht am häufigsten genutzt wird.

Doch es gibt auch andere Elemente, die Sie verwenden können, z. B. command für Terminalbefehle. Daneben gibt es Elemente wie synopsis, cmdsynopsis, userinput, varname, replaceable, constant und viele mehr, über die Sie im Standard-Elementverzeichnis mehr erfahren können. Bitte gehen Sie bei der Auswahl von Elementen zur Kennzeichnung von Codebeispielen möglichst einheitlich vor.

So fügen Sie ein Codeelement (oder ein anderes Inline-Element) hinzu:

Markieren Sie den Text, auf den Sie ein Element anwenden möchten.
Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.
Wählen Sie das gewünschte Element aus der Liste aus.

Wählen Sie z. B. code aus.
Geben Sie Ihren Code in das Element ein.
Drücken Sie Speichern.

Beispiel 4. Beispiel für Inline-Code

Angenommen, Sie möchten den Code ssh -1 username remote-address zu einem bestimmten Absatz hinzufügen. Dazu setzen Sie den Cursor an die entsprechende Stelle im para-Element und fügen dann das Inline-code-Element hinzu.

Sie tippen den Code ssh -1 username remote-address in das code-Element ein. Im veröffentlichten Dokument enthält der Absatz einen Mix aus normalem Text und Code, etwa wie folgt:

Um sich an einem anderen Gerät anzumelden, geben Sie den Benutzernamen ssh -l username remote-address ein und drücken Sie Enter.

Code aus einer externen Quelle einbetten

Sie können die Inhalte Ihrer Hilfe so einstellen, dass stets die neuesten Codebeispiele aus einem Datenspeicher wie GitHub oder BitBucket verwendet werden sollen. Anschließend kann Ihre HTML5-Hilfe Codebeispiele auch ohne erneute Veröffentlichung automatisch aktualisieren.

Anmerkung

Die Codebeispiele müssen in einer „https“-URL enthalten sein.

Tipp

Zum Einbetten von Swagger/Open API-Code siehe Swagger OpenAPI einbetten.

Damit Ihre HTML5-Hilfe auf „Live“-Codefragmente aus einem Datenspeicher zugreifen kann, verwenden Sie dynamische Codefragmente.

Wählen Sie im oberen Menü Layout aus.

Paligo zeigt eine Liste von Layouts an. Die Liste ist leer, wenn keine benutzerdefinierten Layouts in Ihrer Paligo-Instanz vorhanden sind.
Wählen Sie das Layout, das Sie aktualisieren möchten, oder Ein Layout erstellen aus.

Tipp

Sie können die URL des Layout-Editors kopieren und in eine neue Registerkarte in Ihrem Browser einfügen. Dies kann nützlich sein, wenn Sie häufig zwischen Ihren Paligo-Inhalten und den Layout-Einstellungen wechseln.
Wählen Sie auf der Seitenleiste Klassen und Attribute aus.
Wählen Sie Aktivieren für Ausgabe von role-Attributen als Klassennamen.
Drücken Sie Speichern.
Wählen Sie das Topic oder die Komponente im Content Manager aus, um es/sie im Editor zu öffnen.

Alternativ können Sie Topics erstellen und dieses bearbeiten.
Wählen Sie die Stelle aus, an der der Code erscheinen soll.
Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.
Fügen Sie ein Codeblockelement hinzu, entweder programlisting oder screen.
Wählen Sie das programlisting- oder screen-Element im Topic aus.

Tipp

Mit dem Kürzel Alt, können Sie ein programlisting-Element mit diesen Attributen hinzufügen. Anschließend fügen Sie nur noch den URL-Wert hinzu.
Diese Attribute und Werte werden im Panel „Elementattribute“ hinzugefügt:
- das Attribut role mit dem Wert embedcode
- das Attribut xlink:href mit der URL zum Codefragment im Datenspeicher.
Optional: Falls Sie Fallback-Code für andere Ausgabeformate wünschen oder benötigen, fügen Sie das Codefragment auch dem programlisting- bzw. screen-Element hinzu.
Drücken Sie Speichern.

Im veröffentlichten Dokument wird der betreffende Code aus dem Datenspeicher abgerufen und automatisch aktualisiert, sobald er sich ändert.

Anmerkung

Wenn Sie auch in anderen Ausgabeformaten wie PDF veröffentlichen, wird der eingebettete Code zum Zeitpunkt der Veröffentlichung nach wie vor dynamisch abgerufen. Sollten Sie hingegen die Codebeispiele in Ihrem Datenspeicher ändern, werden Sie die PDF-Ausgabe erneut veröffentlichen müssen, damit Paligo die aktuellen Änderungen abrufen kann.

Syntax-Hervorhebung

Zusammenfassung

Bei der Syntax-Hervorhebung werden Farbmarkierungen und Einrückungen auf Codebeispiele angewendet, um die einzelnen Teile des Codes leichter voneinander unterscheidbar zu machen.

Bei der Syntax-Hervorhebung werden Farbmarkierungen und Einrückungen auf Codebeispiele angewendet, um die einzelnen Teile des Codes leichter voneinander unterscheidbar zu machen. Im folgenden Code-Auszug werden mithilfe der Syntax-Hervorhebung die Elemente verschieden eingefärbt. Der Hintergrund ist dunkel und die einzelnen Typen von Code-Elementen sind durch verschiedene Farben hervorgehoben, darunter die var-Angaben in Hellblau und die var-Namen, wie z. B. „icon1“, in Grün.

Some example javascript shown with a black background. Each part of the code is colored differently.

Syntax-Hervorhebungen funktionieren für HTML5 und PDF unterschiedlich, es gibt aber auch einige Gemeinsamkeiten:

Die Syntax-Hervorhebung lässt sich für das Layout, das Sie für die Veröffentlichung nutzen, aktivieren bzw. deaktivieren.
Sie wählen das Topic aus, das für die Syntax-Hervorhebung im Layout angewendet werden soll. Jedes dieser vielen Topics hält jeweils unterschiedliche Farbmuster und Syntax-Hervorhebungen bereit.
In der Regel kann Paligo eine Codesprache in einem verbatim-Element, wie z. B. programlisting, automatisch erkennen. Falls Ihr Codebeispiel doch nicht erkannt werden sollte, können Sie ein language-Attribut verwenden und die Sprache dort einstellen.

Syntax-Hervorhebung für HTML5

Zusammenfassung

Sie können Syntax-Hervorhebungen für HTML5-Ausgaben so einrichten, dass die Syntax von Codebeispielen farblich markiert wird.

Bei der Einrichtung dieser Hervorhebungen in HTML5-Ausgaben verwenden Sie die Einstellungen für HTML5-Layouts und fügen dem Codebeispiel evtl. benötigte Attribute hinzu:

Wählen Sie im oberen Menü Layout aus.

Paligo zeigt eine Liste von Layouts an. Die Liste ist leer, wenn keine benutzerdefinierten Layouts in Ihrer Paligo-Instanz vorhanden sind.
Wählen Sie das Layout, das Sie aktualisieren möchten, oder Ein Layout erstellen aus.

Tipp

Sie können die URL des Layout-Editors kopieren und in eine neue Registerkarte in Ihrem Browser einfügen. Dies kann nützlich sein, wenn Sie häufig zwischen Ihren Paligo-Inhalten und den Layout-Einstellungen wechseln.
Wählen Sie in der Seitenleiste Verbatim (Code und Software) aus.
Mit diesen Einstellungen können Sie die Syntax-Hervorhebung einrichten:
- Verbatim-Elemente hervorheben – Stellen Sie die Syntax-Hervorhebungsfunktion auf Aktivieren (ein) oder Deaktivieren (aus).
- Thema hervorheben – Wählen Sie ein Thema aus. Jedes Topic hält ein anderes Farbschema für syntaktische Hervorhebungen bereit, in dem jeweils verschiedene Teile des Codes hervorgehoben werden können. Es stehen viele verschiedene Themen zur Auswahl und wir empfehlen Ihnen, damit etwas zu experimentieren, bis Sie eines gefunden haben, das Ihren Anforderungen am besten entspricht.
Drücken Sie Speichern.
Paligo ist in der Regel in der Lage, die Sprache eines Codebeispiels automatisch zu erkennen, und wendet das gewählte Thema für die Hervorhebung der Syntax an. Falls Paligo Ihr Codebeispiel nicht erkennt, können Sie ihm ein language-Attribut zuweisen. Paligo kann das Beispiel dann anhand des für language festgelegten Werts identifizieren.

So legen Sie language für ein Codebeispiel fest:
1. Bearbeiten Sie das Topic, das das Codebeispiel enthält, und wählen Sie das Verbatim-Element für das Beispiel aus, z. B. programlisting.
2. Fügen Sie im Abschnitt Elementattribute das Attribut language hinzu und geben Sie als Wert eine unterstützte Sprache ein. Zum Beispiel Javascript. Welche Werte gültig sind, erfahren Sie unter Syntax-Hervorhebung von Sprachen in HTML5.
Drücken Sie Speichern.

Syntax-Hervorhebung von Sprachen in HTML5

Mit dem Attribut language können Sie Codebeispielen eine bestimmte Programmiersprache zuweisen. So können Sie einem programlisting-Element das Attribut language geben und dessen Wert auf javascript setzen.

Informationen zum Hinzufügen des Attributs language finden Sie unter Syntax-Hervorhebung für HTML5.

Die folgende Tabelle enthält die Werte, die Sie für das Attribut language festlegen können. Für einige Sprachen können Sie einen von mehreren Werten verwenden, die in der Tabelle durch ein Komma getrennt sind. Geben Sie nur einen der Werte ein, also z. B. für JavaScript entweder js oder javascript oder jsx.

Programmiersprache	Wert für das Attribut „language“
1C	1c
4D	4d
ABNF	abnf
Access Logs	accesslog
ActionScript	actionscript, as
Ada	ada
Alan	alan, i
AngelScript	angelscript, asc
Apache	apache, apacheconf
AppleScript	applescript, osascript
Arcade	arcade
ARM-Assembler	armasm, arm
AsciiDoc	asciidoc, adoc
AspectJ	aspectj
AutoHotkey	autohotkey
AutoIt	autoit
AVR-Assembler	avrasm
Awk	awk, mawk, nawk, gawk
Axapta	axapta
Bash	bash, sh, zsh
Basis	basic
BNF	bnf
Brainfuck	brainfuck, bf
C	h
C#	csharp, cs
C++	cpp, hpp, cc, hh, c++, h++, cxx, hxx
Cache Object Script	cos, cls
C/AL	cal
Cap’n Proto	capnproto, capnp
Clojure	Clojure, clj
CMake	cmake, cmake.in
CoffeeScript	coffeescript, coffee, cson, iced
Coq	coq
Crmsh	crmsh, crm, pcmk
Crystal	crystal, cr
CSP	csp
CSS	css
Cypher (Neo4j)	cypher
D	d
Dart	dart
Delphi	delphi, dpr, dfm, pas, pascal, freepascal, lazarus, lpr, lfm
Diff	diff, patch
Django	django, jinja
DNS Zone Datei	dns, zone, bind
Dockerfile	dockerfile, docker
DOS	dos, bat, cmd
dsconfig	dsconfig
DTS (Gerätebaum)	dts
Dust	dust, dst
Dylan	dylan
EBNF	ebnf
Eigenschaften	properties
Elixir	elixir
Elm	elm
Erlang	erlang, erl
Excel	excel, xls, xlsx
Extempore	extempore, xtlang, xtm
F#	fsharp, fs
FIX	fix
Fortran	fortran, f90, f95
Gams	gams, gms
GAUSS	gauss, gss
G-Code	gcode, nc
GDScript	godot, gdscript
Gherkin	gherkin
GN for Ninja	gn, gni
Go	go, golang
Golo	golo, gololang
Gradle	gradle
Grammatical Framework	gf
Groovy	groovy
Haml	haml
Handlebars	handlebars, hbs, html.hbs, html.handlebars
Haskell	haskell, hs
Haxe	haxe, hx
HTML, XML	xml, html, xhtml, rss, atom, xjb, xsd, xsl, plist, svg
HTTP	http, https
Hy	hy, hylang
Inform7	inform7, i7
Ini, TOML	ini, toml
IRPF90	irpf90
Java	java, jsp
JavaScript	javascript, js, jsx
JSON	json
Kotlin	kotlin, kt
Lasso	lasso, ls, lassoscript
LaTeX	tex
LDIF	ldif
Leaf	leaf
Less	less
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, mk, mak
Markdown	markdown, md, mkdown, mkd
Mathematica	mathematica, mma, wl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercury	mercury
mIRC Scripting Language	mirc, mrc
Mizar	mizar
Mojolicious	mojolicious
Monkey	monkey
Moonscript	moonscript, moon
N1QL	n1ql
Nginx	nginx, nginxconf
Nim	nimrod
Nix	nix
NSIS	nsis
Objective C	objectivec, mm, objc, obj-c
OCaml	ocaml, ml
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Oracle Rules Language	ruleslanguage
Oxygene	oxygene
Parser3	parser3
Perl	perl, pl, pm
PF	pf, pf.conf
PHP	php, php3, php4, php5, php6, php7
Plaintext	plaintext, txt, text
Pony	pony
PostgreSQL und PL/pgSQL	pgsql, postgres, postgresql
PowerShell	powershell, ps, ps1
Processing	processing
Prolog	prolog
Protocol Buffers	protobuf
Puppet	puppet, pp
Python	python, py, gyp
Python Profiler Ergebnisse	profile
Q	k, kdb
QML	qml
R	r
Razor CSHTML	cshtml, razor, razor-cshtml
ReasonML	reasonml, re
RenderMan RIB	rib
RenderMan RSL	rsl
Roboconf	graph, instances
Robot Framework	robot, rf
RPM Spec-Dateien	rpm-specfile, rpm, spec, rpm-spec, specfile
Ruby	ruby, rb, gemspec, podspec, thor, irb
Rust	rust, rs
SAS	SAS, sas
Scala	scala
Scheme	scheme
Scilab	scilab, sci
SCSS	scss
Shape Expressions	shexc
Shell	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
SQL	sql
Stan	stan, stanfuncs
Stata	stata
STEP Part 21	p21, step, stp
Structured Text	iecst, scl, stl, structured-text
Stylus	stylus, styl
SubUnit	subunit
Supercollider	supercollider, sc
Swift	swift
Tcl	tcl, tk
Terraform (HCL)	terraform, tf, hcl
Test Anything Protocol	tap
Thrift	thrift
TP	tp
Twig	twig, craftcms
TypeScript	typescript, ts
Vala	vala
VB.Net	vbnet, vb
VBScript	vbscript, vbs
Verilog	verilog, v
VHDL	vhdl
Vim Script	vim
x86 Assembly	x86asm
XL	xl, tao
XQuery	xquery, xpath, xq
YAML	yml, yaml
Zephir	zephir, zep

Syntax-Hervorhebung für PDF

Zusammenfassung

Sie können Syntax-Hervorhebungen für PDF-Ausgaben so einrichten, dass für die Syntax von Codebeispielen unterschiedliche Farben verwendet werden.

Verwenden Sie ein PDF-Layout, um Syntax-Hervorhebungen für PDF einzurichten:

Wählen Sie im oberen Menü Layout aus.

Paligo zeigt eine Liste von Layouts an. Die Liste ist leer, wenn keine benutzerdefinierten Layouts in Ihrer Paligo-Instanz vorhanden sind.
Wählen Sie das Layout, das Sie aktualisieren möchten, oder Ein Layout erstellen aus.

Tipp

Sie können die URL des Layout-Editors kopieren und in eine neue Registerkarte in Ihrem Browser einfügen. Dies kann nützlich sein, wenn Sie häufig zwischen Ihren Paligo-Inhalten und den Layout-Einstellungen wechseln.
Wählen Sie Verbatim (Code und Software) sowie Syntax-Hervorhebung.
In den Einstellungen können Sie Syntax-Hervorhebungen für Ihre PDF-Ausgabe einrichten:
- Syntax-Hervorhebung einschalten – Stellen Sie die Syntax-Hervorhebungsfunktion auf Aktiviert (ein) oder Deaktiviert (aus).
- Standardsprache, wenn kein language-Attribut festgelegt wurde – Wenn für die Codebeispiele in Ihren Topics keine Sprache festgelegt wurde, kann Paligo die Sprache eines Codebeispiels in der Regel automatisch erkennen. Sollte die Sprache jedoch nicht identifizierbar sein, geht es davon aus, dass das Codebeispiel in der Standardsprache verfasst wurde. Mit dieser Einstellung legen Sie die Standardsprache fest.
- Standardstil für Syntax-Hervorhebung – Wählen Sie ein Topic aus. Jedes Topic hält ein anderes Farbschema für syntaktische Hervorhebungen bereit, in dem jeweils verschiedene Teile des Codes hervorgehoben werden können. Wir empfehlen Ihnen, mit den Topics etwas zu experimentieren, bis Sie eines gefunden haben, das Ihren Anforderungen am besten entspricht.
Anmerkung

Standardsprache und Standardstil kommen nur dann zum Einsatz, wenn für ein Codebeispiel keine eigenen Attribute für Sprache und Stil festgelegt sind.
Drücken Sie Speichern.
Mit dem Attribut language können Sie eigene Sprach- und Stileinstellungen für ein Codebeispiel festlegen, die dann anstelle der Standardeinstellungen verwendet werden. Dies ist hilfreich, wenn Paligo die Sprache nicht automatisch erkennen kann.
1. Bearbeiten Sie das Topic, das das Codebeispiel enthält, und wählen Sie das Verbatim-Element für das Beispiel aus, z. B. programlisting.
2. Fügen Sie im Abschnitt Elementattribute das Attribut language hinzu und geben Sie als Wert eine unterstützte Sprache ein. Zum Beispiel Javascript. Welche Werte Sie verwenden können, finden Sie unter Syntax-Hervorhebung von Sprachen für PDFs.
3. Fügen Sie das Attribut role hinzu und geben Sie als Wert einen unterstützten Themennamen ein. Zum Beispiel role: fruchtig. Dieser Schritt ist optional. Üblicherweise und aus Gründen der Einheitlichkeit wird für alle Codebeispiele möglichst das gleiche Topic verwendet. Daher legen Sie ein Standardthema für das Layout fest, anstatt das role-Attribut für einzelne Codebeispiele anzuwenden.
  
  Anmerkung
  
  Sie können als Wert eines der Themen angeben, die im PDF-Layout-Editor unter Standardstil für Syntax-Hervorhebung aufgelistet sind.
Drücken Sie Speichern.

Wenn Sie nun in PDF mit dem von Ihnen bearbeiteten Layout veröffentlichen, wird in der PDF-Ausgabe die Syntax-Hervorhebung angewendet. Wenn ein Codebeispiel eine eigene Sprache und ein eigenes Rollenset nutzt, wendet Paligo diese an. Wurde keine eigene Sprache und kein Rollenset festgelegt, versucht Paligo, die Sprache automatisch zu erkennen, und verwendet das Standardthema. Sollte Paligo die automatische Spracherkennung nicht gelingen, verwendet es die im Layout festgelegte Standardsprache.

Syntax-Hervorhebung von Sprachen für PDFs

Informationen zum Hinzufügen des Attributs language finden Sie unter Syntax-Hervorhebung für PDF.

Die folgende Tabelle enthält die Werte, die Sie für das Attribut language festlegen können. Für einige Sprachen können Sie einen von mehreren Werten verwenden, die in der Tabelle durch ein Komma getrennt sind. Es sollte jeweils nur genau ein Wert ausgewählt werden, z. B. können Sie für JavaScript entweder „js“ oder „javascript“ eingeben.

Sprache	Wert für das Attribut „language“
ABAP	abap
ABNF	abnf
ActionScript	as, actionscript
ActionScript 3	as3, actionscript3
Ada	ada, ada95, ada2005
ADL	adl
Agda	agda
Alloy	alloy
AmbientTalk	at, ambienttalk, ambienttalk/2
ANTLR	antlr
ANTLR mit ActionScript-Ziel	antlr-as, antlr-actionscript
ANTLR mit CPP-Ziel	antlr-cpp
ANTLR mit C#-Ziel	antlr-csharp, antlr-c#
ANTLR mit Java-Ziel	antlr-java
ANTLR mit ObjectiveC-Ziel	antlr-objc
ANTLR mit Perl-Ziel	antlr-perl
ANTLR mit Python-Ziel	antlr-python
ANTLR mit Ruby-Ziel	antlr-ruby, antlr-rb
ApacheConf	apacheconf, aconf, apache
APL	apl
AppleScript	applescript
Arduino	arduino
AspectJ	aspectj
Aspx-cs	aspx-cs
Aspx-vb	aspx-vb
Asymptote	asy, asymptote
Autohotkey	ahk, autohotkey
AutoIt	autoit
Awk	awk, gawk, mawk, nawk
Basemake	basemake
Bash	bash, sh, ksh, shell
Bash Session	console, shell-session
Batchfile	bat, batch, dosbatch, winbatch
BBCode	bbcode
BC	bc
Befunge	befunge
BlitzBasic	blitzbasic, b3d, bplus
BlitzMax	blitzmax, bmax
BNF	bnf
Boo	boo
Boogie	boogie
Brainfuck	brainfuck, bf
Bro	bro
BUGS	bugs, winbugs, openbugs
C	c:
C#	csharp, c#
C++	cpp, c++
CA65 Assembler	ca65
cADL	cadl
CAmkES	camkes, idl4
CBM BASIC V2	cbmbas
Ceylon	ceylon
CFEngine3	cfengine3, cf3
Cfstatement	cfs
ChaiScript	chai, chaiscript
Chapel	chsprl, chpl
Cheetah	cheetah, spitfire
Cirru	cirru
Clay	clay
Clojure	Clojure, clj
ClojureScript	clohurescript, cljs
CMake	cmake
C-Objdump	c-objdump
COBOL	cobol
COBOLFree	cobolfree
Coffee-script	coffee-script, coffeescript, coffee
Coldfusion CFC	cfc
Coldfusion HMTL	cfm
Common Lisp	common-lisp, cl, lisp
Component Pascal	componentpascal, cp
Control, Debian Control	control, debcontrol
Coq	coq
Cpp-Objdump	cpp-objdump, c++-objdumb, cxx-objdump
CPSA	cpsa
Crmsh	crmsh, pcmk
Croc	croc
Cryptol	cryptol, cry
Csound Document	csound-document, csound-csd
Csound Orchestra	csound, csound-orc
Csound Score	csound-score, csound-sco
CSS	css
CSS+Django, CSS+Jinja	css+django, css+jinja
CSS+Erb, CSS+Ruby	css+erb, css+ruby
CSS+Genshitext, CSS+Genshi	css+genshitext, css+genshi
CSS+Lasso	css+lasso
CSS+Mako	css+mako
CSS+Mozpreproc	css+mozpreproc
CSS+Myghty	css+myghty
CSS+PHP	css+php
CSS+Smarty	css+smarty
CUDA	cuda, cu
Cypher	cypher
Cython	cython, pyx, pyrex
D	d
Dart	dart
Debian Sourcelist	sourceslist, sources.list, debsources
Delphi	delphi, pas, pascal, objectpascal
DG	dg
Diff	diff, udiff
Django/Jinja	django, jinja
D-Objdump	d-objdump
Docker	dockerfile, docker
Dpatch	dpatch
DTD	dtd
Duel	duel, jbst, jsonml+bst
Dylan	dylan
DylanLID	dylan-lid, lid
Dylan Session	dylan-console, dylan-repl
Earl Grey	earl-grey, earlgrey, eg
Easytrieve	easytrieve
EBNF	ebnf
eC	ec
ECL	ecl
Eiffel	eiffel
Eigenschaften	properties, jproperties
Elixir	elixir, ex, exs
Elixir iex Sitzung	iex
Elm	elm
EmacsLisp	emacs, elisp, emacs-lisp
ERB	erb
Erlang	erlang
Erlang ERL-Sitzung	erl
Evoque	evoque
Ezhil	ezhil
Faktor	Faktor
Fancy	fancy, fy
Fantom	fan
Felix	felix, flx
Fish	fish, fishshell
Fortran	fortran
FortranFixed	fortranfixed
FoxPro, VFP, Clipper, XBase	foxpro, vfp, clipper, xbase
FSharp	fsharp
GAP	gap
GAS	gas, asm
Genshi	genshi, kid, xml+genshi, xml+kid
Genshi Text	genshitext
Gettext Catalog	pot, po
Gherkin	cucumber, gherkin
GLSL	glsl
Gnuplot	gnuplot
Go	go
Golo	golo
GoodData-CL	gooddata-cl
Gosu	gosu
Gosu-Vorlage	gst
Groff	groff, nroff, man
Groovy	groovy
Haml	haml
Handlebars	Handlebars
Haskell	haskell, hs
Haxe	hx, haxe, hxsl
Hexdump	Hexdump
HTML	html
HTML+Cheetah	html+cheetah, html+spitfire, htmlcheetah
HTML+Django/Jinja	html+django, html+jinja, htmldjango
HTML+Evoque	html+evoque
HTML+Genshi	html+genshi, html+kid
HTML+Handlebars	html+handlebars
HTML+Lasso	html+lasso
HTML+Mako	html+mako
HTML+Myghty	html+myghty
HTML+PHP	html+php
HTML+Smarty	html+smarty
HTML_Twig	html+twig
HTML+Velocity	html+velocity
HTTP	http
HXML	haxeml, hxml
Hy	hylang
Hybris	hybris, hy
IDL	idl
Idris	idris, idr
Igor	igor, igorpro
Inform 6	inform6, i6
Inform 6 Vorlage	i6t
Inform7, i7	inform7, i7
INI	ini, cfg, dosini
Io	io
Ioke	ioke, ik
IRC-Protokolle	irc
Isabelle	isabelle
J	j
Jade	jade
JAGS	jags
Jasmin	jasmin, jasminxt
Java	java
JavaScript	js, javascript
JavaScript+Cheetah	js+cheetah, javascript+cheetah, js+spitfire, javascript+spitfire
JavaScript+Django/Jinja	js+django, javascript+django, js+jinja, javascript+jinja
JavaScript+Genshitext	js+genshitext, js+genshi, javascript+genshitext, javascript+genshi
JavaScript+Lasso	js+lasso, javascript+lasso
JavaScript+Mako	js+mako, javascript+mako
Javascript+Mozpreproc	javascript+mozpreproc
JavaScript+Myghty	js+myghty, javascript+myghty
JavaScript+PHP	js+php, javascript+php
Javascript+Ruby	js+erb, javascript+erb, js+ruby, javascript+ruby
JavaScript+Smarty	js+smarty, javascript+smarty
Java Server Seite	jsp
JCL	jcl
JLCON Julia Console	jlcon
JSON	json
JSON-LD	jsonld, json-ld
Julia	julia, jl
Kal	kal
Kconfig	kconfig, menuconfig, linux-config, kernel-config
Koka	koka
Kotlin	kotlin
Lasso	lasso, lassoscript
Lean	lean
LessCSS	less
Lighttpd-Konfiguration	lighty, lighttpd
Limbo	limbo
Liquid	liquid
Literate Cryptol	lcry, literate-cryptol, lcryptol
Literate-Haskell	lhs, literate-haskell, lhaskell
Literate Idris	lidr, literate-idris, lidris
Literate Lagda	lagda, literate-agda
Live-Script	live-script, livescript
LLVM	llvm
Logos	logos
Logtalk	logtalk
LSL	lsl
Lua	lua
Makefile	make, makefile, mf, bsdmake
Mako	mako
MAQL	maql
Mask	mask
Mason	mason
Mathematica	mathematica, mma, nb
Matlab	matlab
Matlab-Sitzung	matlabsession
MiniD	minid
Modelica	modelica
Modula-2	modula2, m2
MoinMoin/Trac Wiki-Markup	trac-wiki, moin
Monkey	monkey
MOOCode	moocode, moo
MoonScript	moon, moonscript
Mozhashpreproc	mozhashpreproc
Mozpercentpreproc	mozpercentpreproc
MQL	mql, mq4, mq5, mql4, mql5
Mscgen	mscgen, msc
MSDOS-Sitzung	doscon
MuPAD	mupad
MXML	mxml
Myghty	myghty
MySQL	mysql
NASM	nasm
Nemerle	nemerle
nesC	nesc
NewLisp	newlisp
Newspeak	newspeak
Nginx-Konfiguration	nginx
Nimrod	nimrod, nim
Nit	nit
Nix	nixos, nix
NSIS	nsis, nsi, nsh
NumPy	numpy
Nur Text	text
Objdump	objdump
Objdump-nasm	objdump-nasm
Objective-C	objective-c, objectivec, obj-c, objc
Objective-C++	objective-c++, objectivec++, obj-c++, objc++
Objective-J	objective-j, objectivej, obj-j, objj
OCaml	ocaml
Octave	octave
ODIN	odin
Ooc	ooc
Opa	opa
OpenEdge ABL	openedge, abl, progress
PacmanConf	pacmanconf
Pan	pan
Parasail	parasail
Pawn	pawn
Perl	perl, pl
Perl6	perl6, pl6
PHP	php, php3, php4, php5
Pig	pig
Pike	pike
PkgConfig	pkgconfig
plpgsql	PL/pgSQL
PostgreSQL	postgresql, postgres
PostgreSQL console	psql, postgresql-console, postgres-console
PostScript	postscript, postscr
POVRay	pov
PowerShell	powershell, posh, ps1, psm1
PowerShell-Sitzung	ps1con
Praat	praat
Prolog	prolog
Protocol Buffer	protobuf,proto
Puppet	puppet
Python 3	python3, py3
Python 3.0 Traceback	py3tb
Python-Konsolensitzung	pycon
QBasic	qbasic, basic
QML	qml, qbs
QVTO	qvto, qvt
Racket	racket, rkt
Ragel	ragel
Ragel in C Host	ragel-c
Ragel in CPP Host	ragel-cpp
Ragel in D Host	ragel-d
Ragel in Java Host	ragel-java
Ragel in Objective C Host	ragel-objc
Ragel in Ruby Host	ragel-ruby, ragel-rb
Ragel – eingebettet	ragel-em
Raw token data	raw
RConsole	rconsole, rout
Rd	rd
REBOL	rebol
Red	red, red/system
Redcode	redcode
Reg	registry
ResourceBundle	resource, resourcebundle
reStructuredText	rst, rest, restructuredtext
Rexx	rexx, arexx
RHTML	rhtml, html+erb, html+ruby
Roboconf Graph	roboconf-graph
Roboconf Instances	roboconf-instances
RobotFramework	robotframework
RPMSpec	spec
RQL	rql
RSL	rsl
Ruby	rb, ruby, duby
Ruby irb Sitzung	rbcon, irb
Rust	rust
S	splus, s, r
Sass	sass
Scala	scala
Scalate Server Page	ssp
Scaml	scaml
Scheme	scheme, scm
Scilab	scilab
SCSS	scss
Shen	shen
Slim	slim
Smali	smali
Smalltalk	smalltalk, squeak, st
Smarty	smarty
Snobol	snobol
SourcePawn	sp
SPARQL	sparql
SQL	sql
sqlite3con	sqlite3
SquidConf	squidconf, squid.conf, squid
Stan	stan
Standard ML	sml
SuperCollider	sc, supercollider
SWIG	swig
systemverilog	systemverilog, sv
TADS 3	tads3
TAP	tap
Tcl	tcl
Tcsh	tcsh, csh
Tea	tea
Termcap	termcap
Terminfo	terminfo
Terraform	terraform, tf
TeX	tex, latex
Thrift	thrift
Todotxt	todotxt
TrafficScript	rts, trafficscript
Treetop	treetop
Turtle	turtle
Twig	twig
TypeScript	ts, typescript
UrbiScript	urbiscript
Vala	vala, vapi
VB.net	vb.net, vbnet
VCTreeStatus	vctreestatus
Velocity	velocity
Verilog, v	verilog, v
VGL	vgl
vhdl	vhdl
VimL	vim
X10	x10, xten
XML	xml
XML+Cheetah	xml+cheetah, xml+spitfire
XML+Django/Jinja	xml+django, xml+jinja
XML+Evoque	xml+evoque
XML+Lasso	xml+lasso
XML+Mako	xml+mako
XML+Myghty	xml+myghty
XML+PHP	xml+php
XML+Ruby	xml+erb, xml+ruby
XML+Smarty	xml+smarty
XML+Velocity	xml+velocity
XSLT	xslt
xsltXQuery	xquery, xqy, xq, xql, xqm
Xtend	xtend
XUL+mozpreproc	xul+mozpreproc
YAML	yaml
YAML+Jinja	yaml+jinja, salt, sls
Zephir	zephir

Swagger OpenAPI einbetten

Um Swagger Open API-Inhalte in Paligo zu verwenden, können Sie sie entweder einbetten oder Swagger OpenAPI importieren. Welcher Ansatz für Sie am besten geeignet ist, hängt von Ihren Anforderungen ab.

Die Einbettung ist vorteilhaft, wenn Ihre Swagger Open API-Inhalte an anderer Stelle im Internet, außerhalb von Paligo, vorhanden sind. Durch das Einbetten fügen Sie eine „Live“-Version der Inhalte zu einem Paligo Topic hinzu. Die Formatierung der Inhalte ist dann jedoch eingeschränkt, da sie sich nicht in der Paligo-Datenbank befinden und daher während der Veröffentlichung nicht von Paligo verarbeitet werden können.
Der Import ist vorteilhaft, wenn Sie die Swagger Open API-Inhalte in Paligo formatieren müssen. Mit einem Import fügen Sie die Swagger Open API-Inhalte der Paligo-Datenbank hinzu, wo Sie die Formatierung genauer steuern können, genau wie bei regulären Paligo-Inhalten. Allerdings müssen Sie die Inhalte bei jeder Aktualisierung manuell importieren .

CORS (Cross-Origin Resource Sharing) definiert eine Möglichkeit für Client-Webanwendungen, die in der einen Domäne geladen werden, mit Ressourcen in einer anderen Domäne zu interagieren. Damit das Einbetten von Swagger funktioniert, muss der Host (auf dem sich Ihre Swagger-Inhalte befinden) CORS zulassen: entweder vollständig oder für die Domäne, in der Sie Ihre Inhalte hosten möchten.

Einbinden von Swagger-Inhalten aktivieren

Um Swagger OpenAPI in Ihre Inhalte einbetten zu können, muss es zunächst in Ihrem layout aktiviert werden.

Wählen Sie im oberen Menü Layout aus.

Paligo zeigt eine Liste von Layouts an. Die Liste ist leer, wenn keine benutzerdefinierten Layouts in Ihrer Paligo-Instanz vorhanden sind.
Wählen Sie das Layout, das Sie aktualisieren möchten, oder Ein Layout erstellen aus.

Tipp

Sie können die URL des Layout-Editors kopieren und in eine neue Registerkarte in Ihrem Browser einfügen. Dies kann nützlich sein, wenn Sie häufig zwischen Ihren Paligo-Inhalten und den Layout-Einstellungen wechseln.
Wählen Sie in der Seitenleiste Analysen und andere Integrationen aus.
Wählen Sie Aktivieren für Einbinden von Swagger-Inhalten aktivieren aus.
Wählen Sie auf der Seitenleiste Allgemein aus.
Aktivieren oder Deaktivieren Sie Eine kurze und flache URL-Struktur für Ausgabedateien verwenden – je nachdem, wo der Inhalt in der Publikationsstruktur platziert wird (Inhaltsverzeichnis):
- Aktivieren Sie diese Option, wenn der Inhalt sich auf der zweiten Ebene oder niedriger befinden wird.
- Deaktivieren Sie diese Option, wenn der Inhalt sich auf der obersten Ebene befindet. Standardmäßig deaktiviert.
Anmerkung

Wählen Sie Deaktivieren, wenn das Topic sich auf der obersten Ebene befinden wird. Standardmäßig deaktiviert.
Drücken Sie Speichern.

Swagger-Inhalte einbetten

Um Swagger-Inhalte veröffentlichen zu können, muss das Topic zunächst als Swagger-Topic festgelegt werden und einen Link zur URL der JSON- oder YAML-Datei Ihrer Swagger-Inhalte enthalten,

Topics erstellen die eingebettet werden sollen.
Wählen Sie das section-Element im Menü „Elementstruktur“ aus.
Wählen Sie Zu Element wechseln aus.
Fügen Sie role-Element in Panel „Elementattribute“ hinzu und setzen Sie den Wert auf swagger-topic.
Positionieren Sie den Cursor, um ein para-Element einzufügen (oder verwenden Sie ein vorhandenes leeres para-Element).
Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.
Geben Sie link ein und wählen Sie es im Menü aus.

Fügen Sie dem link ein role-Attribut mit dem Wert swagger-ui hinzu.
Wählen Sie das link-Element im Menü „Elementstruktur“ aus und wählen Sie Zum Element gehen.
Fügen Sie im Panel „Elementattribute“ die folgenden Attribute hinzu:
- role, setzen Sie den Wert auf swagger-ui
- xlink:href und stellen Sie den Wert auf die URL der JSON- bzw. YAML-Datei Ihres Swagger-Inhalts ein.
  
  Tipp
  
  Falls Ihr Swagger-Inhalt noch nicht zur Verfügung steht, aber die Integration schon getestet werden soll, können Sie das Standardbeispiel „Pet Store“ von Swagger unter der URL https://petstore.swagger.io/v2/swagger.json verwenden.
Drücken Sie Speichern.
Veröffentlichen Sie die Publikation mit dem aktualisierten Layout.

Die Ausgabe sollte etwa wie folgt aussehen: Ein Navigations-Untermenü links für jeden der Endpunkte in Ihrem Swagger-Inhalt, und die gesamte Interaktivität des Swagger-Inhalts sollte funktionieren.

Anmerkung

Wenn Ihnen der Fehler „Keine API-Definition vorhanden“ gemeldet wird, handelt es sich nicht um einen Fehler auf Paligo-Seite. Dies bedeutet in der Regel, dass Sie ein „CORS“-Problem haben – das ist eine Sicherheitseinstellung auf Ihrem Server.

Ob dies der Fall ist, können Sie testen, indem Sie CORS umgehen. Hierfür gibt es CORS-Umgehungserweiterungen, die Sie Ihrem Browser hinzufügen können. Bei eventuellen Unklarheiten wenden Sie sich bitte an Ihr Entwicklungsteam.

Sollten Ihre Tests ergeben, dass CORS ein Problem verursacht, bitten Sie Ihre Entwickler, CORS auf dem Server zu aktivieren, auf dem Sie Ihre Swagger-Inhalte hosten.

Bitte beachten Sie, dass Paligo keine Verantwortung dafür übernimmt, wie Sie CORS-Probleme testen.

Sollten Probleme beim Einbetten von Swagger, das in Amazon S3 gehostet wird, auftreten, schauen Sie bitte in die Amazon CORS-Konfiguration.

Code in Zwischenablage kopieren

Paligo verfügt über eine Funktion In die Zwischenablage kopieren, die Sie für Ihre Codebeispiele nutzen können.

Wenn die Funktion aktiviert ist, erscheint für jedes programlisting-Element eine Schaltfläche „Kopieren“, mit der sich das Codebeispiel aus dem Element in die Zwischenablage ihres Computers kopieren lässt. So können Ihre Leser den exakten Code aus Ihren Beispielen als Ausgangspunkt für ihre eigenen Programme verwenden.

A section of a topic in an HTML output. There is a code sample in the content, and to the right of the code, a copy to clipboard icon.

Schaltfläche „Kopieren“ für alle programlisting-Elemente.

So aktivieren oder deaktivieren Sie die Code-Kopier-Funktion:

Wählen Sie im oberen Menü Layout aus.

Paligo zeigt eine Liste von Layouts an. Die Liste ist leer, wenn keine benutzerdefinierten Layouts in Ihrer Paligo-Instanz vorhanden sind.
Wählen Sie das Layout, das Sie aktualisieren möchten, oder Ein Layout erstellen aus.

Tipp

Sie können die URL des Layout-Editors kopieren und in eine neue Registerkarte in Ihrem Browser einfügen. Dies kann nützlich sein, wenn Sie häufig zwischen Ihren Paligo-Inhalten und den Layout-Einstellungen wechseln.
Wählen Sie in der Seitenleiste Analysen und andere Integrationen aus.
Deaktivieren Sie Rendern der MathJax-Gleichung aktivieren.
Wählen Sie in der Seitenleiste Verbatim (Code und Software) aus.
Mit der Schaltfläche Kopie in Zwischenablage zu allen programlistings hinzufügen können Sie steuern, ob die Schaltfläche Kopieren enthalten ist:
- Setzen Sie sie auf 1, um die Kopierschaltfläche für jedes programlisting-Element in Ihrer HTML5-Ausgabe aufzunehmen.
- Setzen Sie sie auf 0 oder auf Standard, wenn Sie sie nicht einschließen möchten.
Drücken Sie Speichern.

Wenn Sie bei aktivierter Funktion Ihre Inhalte mit diesem Layout veröffentlichen, haben die programlistings eine Schaltfläche „Kopieren“.

Layout der API-Dokumentation

Paligo bietet Ausgaben im API-Stil, welcher speziell für die Entwicklerdokumentation entwickelt wurde. Dieser liefert moderne, ansprechende API-Dokumentationsausgaben, einschließlich Navigation, und Ihre Inhalte und Codebeispiele werden nach Sprachen sortiert in einer Seitenleiste rechts angezeigt.

Tipp

Erfahren Sie mehr unter Paligo-REST-API und Paligo API.

So verwenden Sie die Ausgabe im API-Stil

Um die Ausgabe im API-Stil verwenden zu lönnen, müssen Sie Ihre Inhalte mit bestimmten Elementen wie programlisting oder code kennzeichnen. Außerdem müssen Sie in HTML5 veröffentlichen und ein HTML5-API-Stil-Layout verwenden.

Programlisting- und example-Elemente auf der obersten Ebene (direkt unter dem Stamm-Abschnittselement) werden automatisch in der rechten Seitenleiste aufgeführt und mit dem Text im Haupttext synchronisiert.

Tipp

Da diese Elemente neben jedem Abschnitt angeordnet werden, funktioniert es am besten, wenn die Beispiele nicht zu lang sind und jedes Hauptbeispiel in einem separaten Abschnitt oder Topic behandelt wird.

Für Codeelemente (programlisting und code) wird die im DocBook integrierte Attribut-language verwendet. Damit legen Sie fest, auf welche Programmiersprache sich der Code bezieht.
Für alle übrigen Elemente gibt es ein spezielles Paligo-Attribut namens xinfo:proglang. Es dient zum Filtern von Inhalten in beliebigen Elementen – außer Tabellenzeilen. Sie können es auch zum Umschalten zwischen example- und informalexample-Elementen in der Seitenleiste verwenden.
Wenn Sie ein bestimmtes Beispiel aus der Seitenleiste ausschließen und inline im Fließtext anzeigen möchten, können Sie dies wie folgt umsetzen:
1. Entweder auf der ersten Ebene unter „section“ an beliebiger Stelle platzieren oder
2. das role-Attribut zu example oder informalexample hinzufügen und auf „inline-example“ setzen. Damit dies funktioniert, müssen Sie außerdem in Ihrem HTML5-Layout die Ausgabe von role-Attributen als Klassennamen im Layout-Editor aktivieren.
Wenn Sie in Ihren Beispielen nur eine einzige Programmiersprache nutzen, wird die Code-Umschalter-Navigationsleiste automatisch ausgeblendet.
Wenn Sie alle Sprachoptionen anzeigen möchten, deaktivieren Sie den Code-Umschalter.

Sie können den Code-Umschalter aber auch dann deaktivieren, wenn Ihre Beispiele in verschiednenen Sprachen verfasst sind, um alle Beispiele für alle Inhalte anzuzeigen.

Dies kann der Fall sein, wenn Sie statt einer API mit mehreren Sprachversionen eine Entwickler- oder andere Softwaredokumentation erstellen, bei der für verschiedene Funktionen unterschiedliche Programmiersprachen zum Einsatz kommen und alle angezeigt werden sollen. Stellen Sie hierfür im Layout-Editor unter „Verbatim (Codeelemente)“ den Parameter Code-Umschalter für API-Style-Ausgabe verwenden auf 0 (deaktiviert) .

Anmerkung

Falls Sie mehr Sprachoptionen haben als die HTML5-Seitenleiste im API-Stil aufnehmen kann, erscheint ein Dropdown-Menü mit den nicht angezeigten Sprachen.

Wenn Sie daraus eine Sprache auswählen, erscheint diese Sprache als Bezeichnung über dem Dropdown-Menü.

Tipp

Falls Sie keine eigenen API-Inhalte haben, aber mit dem API-Layout experimentieren möchten, können Sie Swagger/Open API-Inhalte von https://petstore.swagger.io/v2/swagger.json verwenden.

Legen Sie den Swagger/Open API-Inhalt in einen Ordner auf Ihrem Computer und komprimieren Sie ihn in eine ZIP-Datei. Importieren Sie dann die Zip-Datei mit dem Swagger OpenAPI importieren in Paligo.

Oder Sie importieren dieses von uns erstellte Beispielprojekt: https://paligo.zendesk.com/hc/en-us/articles/360007352034-Download-API-Sample-Content. Importassistenten verwenden Hierzu müssen Sie das Beispielprojekt als Paligo-Exportdatei (PEF) importieren.

Software- und Codedokumentation

Tipp

Allgemeine Softwareelemente

Codeblöcke in Ihren Inhalten

Anmerkungen zu Codeblöcken erstellen

Tipp

Code in einem Absatz (Inline-Code)

Code aus einer externen Quelle einbetten

Anmerkung

Tipp

Tipp

Tipp

Anmerkung

Syntax-Hervorhebung

Syntax-Hervorhebung für HTML5

Tipp

Syntax-Hervorhebung von Sprachen in HTML5

Syntax-Hervorhebung für PDF

Tipp

Anmerkung

Anmerkung

Syntax-Hervorhebung von Sprachen für PDFs

Swagger OpenAPI einbetten

Einbinden von Swagger-Inhalten aktivieren

Tipp

Anmerkung

Swagger-Inhalte einbetten

Tipp

Anmerkung

Code in Zwischenablage kopieren

Tipp

Layout der API-Dokumentation

Tipp

So verwenden Sie die Ausgabe im API-Stil

Tipp

Anmerkung

Tipp

Suchresultat