Software and Code Documentation

General Software Elements

Even if you are not documenting much code, if you document software you'll often have to refer to parts of the software product, such as UI components, file names, tags, keyboard shortcuts, etc. Here are some common elements to use:

Example 40. UI components

The easiest way to refer to UI components (buttons, menus, toolbars, etc) is to use one element as a generic UI element: guilabel. Here's an example:

Click on the Ok button.

Since this is so common (and recommended practice instead of using bold or italic for such terms), there is also a keyboard shortcut for it: AltG.

If you want to be more granular, you can use very specific elements instead, using guilabel only for labels, guibutton for buttons, guimenu and its sub elements for menus, etc.

Another common need is to write file names and paths, and for this you have the element filename.

Example 41. Keyboard shortcuts

To write keyboard shortcuts properly, and give you the option for how to style them now or change it later, or use different styling for different outputs, use the keycap element:

Hit AltK to add a keycap element.

As you can see, this element can be styled, and here it is styled as keyboard keys, and as the example shows this element has a keyboard shortcut itself for convenience.

If you want, you can use it separately, or in combination with the keycombo element. If keycap elements are wrapped in a keycombo element, by default it will output a "+" symbol between the keys (which can be customized in stylesheets if needed).

Code Blocks in your Content

One of the most common needs when documenting software is to write code blocks. The main element for this is programlisting.

To add a programlisting element:

Position the cursor at the start of the line where you want to add the code block.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Search for the programlisting element and select it.

When you add a programlisting element, a code snippet box appears in the topic.
Add your code inside the code snippet box.

The programlisting element is sometimes referred to as "verbatim", as the code you add inside the element will be rendered exactly how it appears in the editor. For example, it will keep spaces and line breaks to represent the code properly. Some other elements also work like this, such as screen and literallayout.

Example 42. Programlisting sample

Here, a javascript function has been added inside a programlisting element. This is how the code looks in the output.

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	This is a javascript function
2	This sets a value to an element using the DOM model.

In the sample shown , a code block is added inside the programlisting element. The javascript function contains (1) on the first line and (2) on the last line. These are callouts, which you can use to annotate code blocks.

Annotate Code Blocks

You can annotate code blocks by using the calloutlist element and co elements. In the published output, the callouts act as clickable "hotspots" that highlight parts of the code. When someone selects a "hotspot", they are taken to the callout text explanation for that "hotspot".

For example, in the image below, the code sample has two callout "hotspots" labelled 1 and 2. Below the code sample, there are numbers that match the hotspots, and next to each number is an annotation that explains the purpose of the corresponding code.

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.

To annotate code using calloutlist:

Select a position in the code block where you want a callout "hotspot" to appear.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Select the co element and give it an xml:id value in the Element attributes section. Each co element has to have an xml:id value that is unique in that specific topic. For example, you could give the first co element the xml:id id_1, the second co element the xml:id id_2 and so on.
Add a calloutlist element after the programlisting element that contains your code block.

Tip

It can be a good idea to include the programlisting and calloutlist elements inside an example element, so that they are all in a single "container" (the example element).
Give each callout in the calloutlist an xml:id as well, different from the ones in the co elements, e.g "callout_1", "callout_2". Again, these ids need to be unique.
Associate the co elements with the callout elements:
1. For each co element, add a linkends attribute. Set the value of the linkends attribute to the xml:id value of the callout that you want to associate it with.
2. For each callout element, add the arearefs attribute. Set the value of the arearefs attribute to the xml:id value of the co that you want to associate it with.

Code in a Paragraph (Inline Code)

If you want to include a small snippet of code in a paragraph rather than as a full block of code, you can use an inline element. There are several elements you can use for this purpose, but perhaps the most commonly used is code.

But there are other elements you can use too. For example, for terminal commands, you might want to use the command element. There are also elements like synopsis, cmdsynopsis, userinput, varname, replaceable, constant, and many more that you can read more about in the standard Element Reference. The important thing is to be consistent when choosing elements for marking up code samples.

To add a code element (or any other inline element):

Highlight the text to which you want to apply an element.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Select the element that you want from the list.

For example, choose code.
Enter your code inside the element.
Select Save.

Example 43. Inline code sample

Let's say you wanted to add the code ssh -1 username remote-address to a paragraph in your content. To do that, you place the cursor at the appropriate position in the para element, and then add the inline code element.

You type the ssh -1 username remote-address code inside the code element and when you publish, the paragraph contains a mix of regular text and code, like this:

To log into another machine type ssh -l username remote-address and hit Enter.

Embed Code from an External Source

You can set your help content to use the latest code samples from a repository, such as GitHub or BitBucket. Once set up, your HTML5 help will be able to update code samples automatically, without being republished.

Note

The code samples need to be in an "https" URL.

Tip

For embedding Swagger/Open API code, see Embed Swagger OpenAPI.

To set up your HTML5 help to use "live" code snippets from a repository, use dynamic code snippets.

Select the Layout tab in the top menu.

Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
Select the layout to be updated or Create a Layout.

Tip

You can copy the URL of the layout editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the layout settings.
Select Classes and attributes in the sidebar.
Select Enable for Output 'role' attribute as class names.
Select Save.
Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Select the position where you want the code to appear.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Add a code block element, either programlisting or screen.
Select the programlisting or screen element in the topic.

Tip

You can add a programlisting element with these attributes added by the shortcut Alt,. Then you just need to add the URL value.
Add these attributes and values In the Element Attributes Panel:
- role attribute with the value embedcode
- xlink:href attribute with the URL to the code snippet in your repository.
Optional: If you want or need fallback code for other output formats, add the code snippet in the programlisting or screen element as well.
Select Save.

When you publish, your code will be fetched from the repository and will be automatically updated if that code changes.

Note

If you also publish to other outputs such as PDF, the embedded code will still be fetched dynamically at publish time. But if you change the code samples in your repository, you will need to republish the PDF output to have Paligo fetch the latest changes.

Syntax Highlighting

Abstract

Syntax highlighting is when code samples use color-coding and indentations to make it easier to differentiate between parts of the code.

Syntax highlighting is when code samples use color-coding and indentations to make it easier to differentiate between parts of the code. In the following code extract, syntax highlighting is used to apply different colors to elements. The background is dark and different colors are used to highlight the different types of code element, for example, var declarations are light blue and the var names, such as icon1, are green.

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

Syntax highlighting works differently for HTML5 and PDF, but there are some common characteristics:

You can enable and disable syntax highlighting on the layout you use for publishing.
You choose the theme to use for syntax highlighting on the layout. There are many themes, each offering different colors and syntax highlighting.
Paligo can usually detect a code language in a verbatim element, such as programlisting, automatically. But if it is not recognizing your code sample, you can apply a language attribute and set the language there.

Syntax Highlighting for HTML5

Abstract

You can set up syntax highlighting for HTML5 outputs so that code samples use colors for the syntax.

To set up syntax highlighting for HTML5 outputs, use the settings on an HTML5 layout, and add attributes to the code sample if required:

Select Layout and then edit the HTML5 layout you are going to use for publishing. Alternatively, you can create a new HTML5 layout and edit that.
On the Layout Editor, open the Verbatim (code and software) settings.
Use the settings to set up syntax highlighting:
- Highlight verbatim elements - Set the syntax highlighting feature to Enable (on) or Disable (off).
- Highlight theme - Choose a theme. Each theme provides a different color scheme for syntax highlighting and may highlight different parts of the code. There are many different themes to choose from and we recommend that you experiment until you find the theme that best meets your requirements.
Paligo will usually be able to recognize the language in a code sample automatically and will apply the chosen theme for syntax highlighting. If Paligo is not recognizing your code sample, you can give the sample a language attribute. Paligo will then be able to identify the sample by the value that's set for the language attribute.

To set the language for a code sample:
1. Edit the topic that contains the code sample and select the verbatim element for the sample, for example, the programlisting element.
2. In the Element attributes section, add the language attribute and enter a supported language as the value. For example, javascript. To find out what values are acceptable, see Syntax Highlighting Languages for HTML5.
Check the box Use gateway to enable IP Allowlisting. Optional

Syntax Highlighting Languages for HTML5

You can use the language attribute to give code samples a specific programming language. For example, you could give a programlisting element the language attribute and set its value to javascript.

To find out how to add the language attribute, see Syntax Highlighting for HTML5.

The following table shows the values that you can set for the language attribute. For some languages, you can use one of several values, and these are separated by a comma in the table. You should only enter one of the values, for example, for JavaScript you can enter either js or javascript or jsx.

Programming language	Value for the language attribute
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
Basic	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 file	dns, zone, bind
Dockerfile	dockerfile, docker
DOS	dos, bat, cmd
dsconfig	dsconfig
DTS (Device Tree)	dts
Dust	dust, dst
Dylan	dylan
EBNF	ebnf
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 & PL/pgSQL	pgsql, postgres, postgresql
PowerShell	powershell, ps, ps1
Processing	processing
Prolog	prolog
Properties	properties
Protocol Buffers	protobuf
Puppet	puppet, pp
Python	python, py, gyp
Python profiler results	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 files	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 Highlighting for PDF

Abstract

You can set up syntax highlighting for PDF outputs so that code samples use colors for the syntax.

Use a PDF layout to set up syntax highlighting for PDF:

Select Layout and then edit the PDF layout you are going to use for publishing. Alternatively, you can create a new PDF layout and edit that.
On the Layout Editor, open the Verbatim (code and software) settings and select Syntax Highlight. Paligo displays the syntax highlighting settings.
Use the settings to set up syntax highlighting for your PDF output:
- Turn syntax highlight on - Set the syntax highlighting feature to Enabled (on) or Disabled (off).
- Default language when no language attribute has been set - If the code samples in your topics do not have a language set, Paligo will usually be able to identify the language automatically. But if it cannot identify the language, it will assume the code sample is in the default language. Use this setting to define the default language.
- Default style for syntax highlight - Choose a theme. Each theme provides a different color scheme for syntax highlighting and may highlight different parts of the code. We recommend that you experiment until you find the theme that best meets your requirements.
Note

The default language and default style are only used if a code sample does not have its own attributes set for language and style.
You can use the language attribute to give a code sample its own language and style settings that will be used instead of the defaults. This is useful if Paligo is unable to recognize the language automatically.
1. Edit the topic that contains the code sample and select the verbatim element for the sample, for example, the programlisting element.
2. In the Element attributes section, add the language attribute and enter a supported language as the value. For example, javascript. To find out what values you can use, see Syntax Highlighting Languages for PDF.
3. Add the role attribute and enter a supported theme name as the value. For example, role: fruity. This is an optional step. Typically, you would want all code samples to use the same theme for consistency, and so would set a default theme on the layout and not use the role attribute on individual code samples.
  
  Note
  
  You can set the value to any theme that is listed in the Default style for syntax highlight setting on the PDF layout editor.
Check the box Use gateway to enable IP Allowlisting. Optional

When you publish to PDF using the layout you edited, the PDF output will use syntax highlighting. If a code sample has its own language and role set, Paligo will apply those. If a code sample does not have its own language and role set, Paligo will attempt to identify the language automatically and will use the default theme. If Paligo cannot identify the language automatically, it will use the default language that is set in the layout.

Syntax Highlighting Languages for PDF

You can use the language attribute to give code samples a specific programming language. For example, you could give a programlisting element the language attribute and set its value to javascript.

To find out how to add the language attribute, see Syntax Highlighting for PDF.

The following table shows the values that you can set for the language attribute. For some languages, you can use one of several values, and these are separated by a comma in the table. You should only enter one of the values, for example, for JavaScript you can enter either js or javascript.

Language	Value for the language attribute
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 with ActionScript Target	antlr-as, antlr-actionscript
ANTLR with CPP Target	antlr-cpp
ANTLR with C# Target	antlr-csharp, antlr-c#
ANTLR with Java Target	antlr-java
ANTLR with ObjectiveC Target	antlr-objc
ANTLR with Perl Target	antlr-perl
ANTLR with Python Target	antlr-python
ANTLR with Ruby Target	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
Elixir	elixir, ex, exs
Elixir iex session	iex
Elm	elm
EmacsLisp	emacs, elisp, emacs-lisp
ERB	erb
Erlang	erlang
Erlang ERL Session	erl
Evoque	evoque
Ezhil	ezhil
Factor	factor
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 Template	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 template	i6t
Inform7, i7	inform7, i7
INI	ini, cfg, dosini
Io	io
Ioke	ioke, ik
IRC logs	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 Page	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 configuration	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 session	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 Session	doscon
MuPAD	mupad
MXML	mxml
Myghty	myghty
MySQL	mysql
NASM	nasm
Nemerle	nemerle
nesC	nesc
NewLisp	newlisp
Newspeak	newspeak
Nginx configuration	nginx
Nimrod	nimrod, nim
Nit	nit
Nix	nixos, nix
NSIS	nsis, nsi, nsh
NumPy	numpy
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 Session	ps1con
Praat	praat
Prolog	prolog
Properties	properties, jproperties
Protocol Buffer	protobuf, proto
Puppet	puppet
Python 3	python3, py3
Python 3.0 Traceback	py3tb
Python console session	pycon
QBasic	qbasic, basic
QML	qml, qbs
QVTO	qvto, qvt
Racket	racket, rkt
Ragel	ragel
Ragel - Embedded	ragel-em
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
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 session	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
Text only	text
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

Embed Swagger OpenAPI

To use Swagger Open API content in Paligo, you can either embed it or Import Swagger OpenAPI. The best approach for you will depend on your requirements.

Embedding is useful if your Swagger Open API content exists elsewhere on the internet, external to Paligo. By embedding it, you add a "live" version of the content to a Paligo topic. However, there are some limitations with how you can format the content, as it is not in the Paligo database and so cannot be processed by Paligo during publishing.
Importing is useful if you need to be able to format the Swagger Open API content in Paligo. With an import, you bring the Swagger Open API content into the Paligo database, where you have more control over the formatting, just like regular Paligo content. But you will need to import the content manually each time it is updated.

CORS (Cross-origin resource sharing) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. For the Swagger embed to work, the host (where your Swagger content is located) must allow CORS. Either completely, or for the domain where you intend to host your content.

Enable Embed Swagger Content

To be able to embed Swagger OpenAPI in your content, it must first be enabled in your layout.

Select the Layout tab in the top menu.

Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
Select the layout to be updated or Create a Layout.

Tip

You can copy the URL of the layout editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the layout settings.
Select Analytics and other integrations in the sidebar.
Select Enable for Enable embedding Swagger content.
Select General in the sidebar.
Enable or Disable Use a short and flat URL structure for output files depending on where the content will be positioned in the publication structure (table of contents):
- Enable this option if the content will be at second level or lower.
- Disable this option if the content will be at top level. Disabled by default.
Note

Select Disable if the topic will be at top-level. Disabled by default.
Select Save.

Embed Swagger Content

To publish Swagger content, the topic must first be set as a swagger topic and include a link to the URL of the JSON or YAML file of your Swagger content.

Create a Topic that will contain the embedded Swagger content.
Select the section element in the Element Structure Menu.
Select Go to element.
Add the role element in Element Attributes Panel and set the value to swagger-topic.
Position the cursor to insert a para element (or use an existing empty para element).
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter link and select it from the menu.

Add a role attribute to the link, with the value swagger-ui.
Select the link element in the Element Structure Menu and choose Go to element.
Add the following attributes in Element Attributes Panel.
- role and set its value to swagger-ui
- xlink:href and set its value to the URL of the JSON or YAML file of your Swagger content.
  
  Tip
  
  If you don't have your Swagger content available yet, but want to test the integration, you can use the standard Swagger "Pet Store" example, using the URL https://petstore.swagger.io/v2/swagger.json.
Select Save.
Publish the publication with the updated layout.

The output should look something like this: a sub navigation menu on the left for each of the endpoints in your Swagger content, and all of the interactivity of the Swagger content should work.

Note

If you get an error saying "No API definition provided", this is not an error on the Paligo side. It usually means that you have a "CORS" issue, which is a security setting on your server.

You can test if this is the issue by bypassing CORS. There are CORS bypass extensions that you can add to your browser for this purpose. If you are uncertain, please consult your development team.

If your testing shows that CORS is causing a problem, ask your developers to enable CORS on the server where you host your Swagger content.

Please note that Paligo takes no responsibility for how you test CORS issues.

If you experience problems embedding Swagger hosted in Amazon S3, refer to Amazon CORS configuration.

Articles in this section

Tip

General Software Elements