Übersetzungshinweis
Leider war es uns noch nicht möglich, diese Seite für Sie auf Deutsch zu übersetzen. Wir zeigen daher stattdessen die englischsprachige Version der Seite und bitten um Verständnis.
Formatting#
This article describes fomore technical side of writing documentation for pretix. It explains how to structure certain types of information, and what syntax to use to do it.
Screenshots#
Take screenshots of the pretix backend in a resolution of 1200 × 800 pixels. Resize your browser window or use the "Responsive Design View" in Firefox by pressing Ctrl + Shift + M. Log in as "Jordan Doe". Manage the "Tutorial Ltd." organizer account. Edit the "Tutorial Conference" event. If the page in question is specific to event series, edit "Tutorial series" instead.
If you do not have access to these accounts or events, edit your screenshots with the top and sidebar of already existing screenshots.
If you are adding the screenshot to help the user with navigating the website, that is, you want them to know they are on the right page, do not use highlighting. If you want to tell the user to interact with one specific element on the page, highlight that element. Use the color OrangeRed #FF4500 (255, 69, 0) for highlighting. Use the Fontawesome-3 arrow symbols and boxes with a width of 0.5em. Take a look at the screenshots in the tutorial to get an idea what it should look like.
Save screenshots in one of the directories in /pretix-docs/site/assets/screens/.
If there is no directory corresponding to your subject, create a new one.
Choose a straightforward and descriptive name for the screenshot.
Use a hyphen-minus - to separate two words in the filename.
Image descriptions#
You can find basic information on how to write a good image description at Axess Lab. This is how you include an image description in markdown:
Example:
Buttons#
Mark all buttons that you want the user to click the following way:
If a button includes an icon, include the icon before the button label:
Example:
The <span class="typo-btn">:fa3-upload: Import vouchers</span> button lets you upload such a list after saving it from a different event.
The Import vouchers button lets you upload such a list after saving it from a different event.
If the button only contains an icon, use the button format on that label:
Change the name and color by clicking the : button.
If the button has a tooltip, follow it up with the tooltip in quotation marks:
In order to **select** existing elements, click the <span class="typo-btn">:fa3-mouse-pointer: </span> "select rows or shapes" button in the top bar.
In order to select existing elements, click the "select rows or shapes" button in the top bar.
Do not mark buttons this way if you are not telling the user to click them. Put them in quotation marks instead.
Navigation paths#
Navigation paths start either from a placeholder ("Your Event") or from the dashboard.
For consistency and accessibility reasons, use this formatting for all navigation paths.
You can insert icons at any point in the path.
Close it with :.
Use → (AltGr + I) between each step.
Put spaces before and after the arrow symbol.
Paths starting from the dashboard automatically begin with an arrow pointing to the first element.
Examples:
<span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Your Organizer</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >Layer1</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >Layer2</span>
<span class="sr-only">Navigationspfad startend auf dem Dashboard</span><span title="Beginnen Sie auf der Backend-Startseite (Klick aufs Logo links oben)">:i-pretix:</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn">Layer1</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn">Layer2</span>
<span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Your Event</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >:fa3-ticket:Products</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >Quotas</span>
NavigationspfadYour Organizer dann Layer1 dann Layer2 Navigationspfad startend auf dem Dashboard dann Layer1 dann Layer2 NavigationspfadYour Event dann Products dann Quotas
Input fields#
Use quotation marks and the label in the exact spelling as it occurs in the UI for interactive elements such as text input fields and drop-down menus. Refer to them explicitly as a "field" or as a "menu".
Example:
In the "Check-in text" field, provide instructions for the person operating the check-in at your event.
Refer to a checkbox as "the checkbox next to [Label]". If the instructions already contain the words "check" or "uncheck", refer to them as "box".
Example:
Use code formatting for the input in those fields. Example:
If the seats on your layout have a distance of
25, you could enter the number30.
Admonitions#
If you want to tell the reader about legal, technical, or irreversible actions, use colored text boxes. The color is based on ISO standards:
- Blue for notes
- Yellow for warnings
Use three exclamation marks and a space !!! followed by the box type.
If you do not specify a title, the title of the box will default to the type ("Note" or "Warning").
Indent the text of the warning with four spaces.
To continue with normal text, insert an empty line and remove the indentation.
Example:
If you use a note or warning box in multiple articles, place it in the include directory.
If you use it in only one article, you do not have to do that.
In that case, include the warning in the article.
To include a reusable text block, use the following formatting:
!!! Note
pretix offers many settings and customizations where you input your own text, for example, the description on the organizer page, the name of your events, and so on.
You will need to provide a translation in every language you choose here for each individual item.
This can amount to a lot of work.
We recommend using no more than two or three languages at a time unless you are working with dedicated translators.
MkDocs also supports other types of admonitions. The pretix documentation currently only uses notes and warnings. If you think it is necessary to use any other type of admonition, talk to the team before you do so.
Icons#
As of 05/2026, pretix uses Font Awesome 3 icons and some custom icons.
You can find these icons in the repo at /overrides/.icons/.
In order to insert an icon into the text, use :fa3-iconname:, where iconname is the filename of the icon minus the file type extension.
For example, use :fa3-transgender-alt: for the icon
and use :i-seat: for
.
Links and cross references#
Do not insert external or internal links without context. Make them as informative as possible in their descriptive text (the part that is visible to readers in the text and looks like a hyperlink). Make them large enough so that the reader can click them without great effort. Single words such as "here" and "next" are not suitable as link text.
Screen readers sometimes read out contextless lists of links. Hearing the link text "here" five times in a row is not very informative. Even without a screen reader, it helpful for the reader if they have a general idea what is behind the link.
MkDocs uses different symbols to precede internal and external links in the documentation visible to readers to make it easier to distinguish between them. You do not have to specify this because it works automatically. The formatting for both types of links is "link text in square brackets, URL/path in round brackets". Insert cross references to a subheading within another (or the same) article work as follows:
If you want to link to the entire article, omit the # symbol and the parts after it. You can also omit parts of the file path that are identical to the path of the current file. Examples:
Our organizer's profile and all the events we are going to create will be found at [https://pretix.eu/tut/](https://pretix.eu/tut/) from now on.
In this tutorial, we will be:
- creating a [personal and organizer account](getting-started.md#creating-an-account)
- setting up our [organizer account](organizer-account.md)
- creating our [event](event.md)
Remove any umlaut from the part of the link after the #.
For example, replace ö with o.
If you link an article that is not yet available (for example due to an open pull request), GitHub will throw a warning. To avoid this, put a space between square and round brackets and leave a corresponding comment starting with "TK":
Placeholders#
Use <span class="typo-placeholder"> ... </span> to mark placeholders outside of navigation paths.
MkDocs will display these the same way as placeholders within navigation paths.
This does not work in combination with button or icons formatting
Example:
A shop created with pretix Hosted will by default be located at https://pretix.eu/<span class="typo-placeholder">OrganizerShortForm</span>/<span class="typo-placeholder">EventShortForm</span>/.
A shop created with pretix Hosted will by default be located at https://pretix.eu/OrganizerShortForm/EventShortForm/.
Line breaks#
Put a line break after each single sentence. If each sentence is not in a single line in the .md file, then reviewing the article through GitHub becomes unnecessarily messy and difficult.
You can use the following command to automatically move every sentence in a text file (Markdown) to a separate line:
Warnung
The name of the output file must be different from the name of the input file, otherwise the command will create an empty file.
This command searches for occurrences of ". " (that is a dot followed by a space) and replaces them with dot followed by space followed by newline. This also adds line breaks after dotted abbreviations. It can also create double empty lines. Edit the output file and remove unnecessary line breaks manually.
Markdown renders single line breaks as spaces. You can remove the trailing space at the end of the sentence. Markdown renders empty lines as line breaks. Place an empty line between every pair of paragraphs.
If want to add additional line breaks to the output text on the website, put at least two spaces at the end of the line of markdown code.
You can insert additional empty lines using <br>.
If you are inserting an image between two paragraphs, but the image concerns the content of only one of the paragraphs, insert additional empty lines.
Insert <br> between the image and the topically separate paragraph.
Articles specific to Germany#
Some articles in our documentary are only relevant for the German-speaking world, for instance because they concern organizations that only exist in Germany. Although we are publishing the rest of our documentation in English first, it makes sense to write these articles in German.
Because of the way MkDocs organizes the navigation on the website, you have to handle these articles in a special way.
Put the main text of the article in the include directory.
Do not put a level 1 heading or title in the file.
Then, create a file with the following content in the docs directory where the article actually belongs: Heading, note on language and include command for the main text.
Example:
# KulturPass
!!! Note "Hinweis"
Since the KulturPass is specific to event organizers within Germany, the following page is also only provided in German.
Should you require assistance with the KulturPass and do not speak this language, please feel free to reach out to <support@pretix.eu>.
Der [KulturPass](https://www.kulturpass.de/) ist ein Programm der deutschen Bundesregierung für alle, die im laufenden Jahr ihren 18. Geburtstag feiern.
Sie erhalten ab ihrem 18. Geburtstag ein Budget von 200 €, das sie für Eintrittskarten, Bücher, CDs, Platten und vieles andere einsetzen können.
Als Ticketing-System stellt pretix einen automatisierten Prozess für den Verkauf von Eintrittskarten über den KulturPass-Marktplatz bereit.
Dieser Artikel erklärt die Einrichtung der Schnittstelle zwischen dem KulturPass-Marktplatz und Ihrem pretix-Shop, die Verwaltung von KulturPass-Bestellungen und den Bestellprozess aus Sicht der Kund\*innen.
## Voraussetzungen
Sie benötigen Zugriff auf ein Veranstalterkonto und mindestens eine Veranstaltung.
Außerdem müssen Sie sich bei kulturpass.de registrieren, einen Shop einrichten und Angebote erstellen.
Falls Sie das nicht bereits getan haben, registrieren Sie Ihr Unternehmen/Ihre Einrichtung zunächst auf der [KulturPass-Webseite](https://storefront.prod.kulturpass.de/seller-registration).
## Anleitung
### Verbindung der Konten
!!! Warning
Ein KulturPass-Shop kann nur mit einem einzigen externen System verbunden werden.
Wenn der KulturPass-Shop mit mehreren externen Systemen verbunden ist, ist es nicht möglich, Bestellungen zu verarbeiten oder Angebote automatisiert an den KulturPass-Marktplatz zu übermitteln.
Eingehende Bestellungen werden automatisch abgelehnt, da sie nicht eindeutig zugeordnet werden können.
Das gilt auch, wenn Sie Ihren KulturPass-Shop mit mehreren pretix-Veranstalterkonten verbinden.
Wenn Sie mehrere Systeme haben, die den KulturPass-Marktplatz bedienen sollen, wenden Sie sich bitte an den KulturPass-Support, um sich einen weiteren Shop einrichten zu lassen.
Um Ihr pretix-Veranstalterkonto mit Ihrem KulturPass-Konto zu verbinden, navigieren Sie zu <span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Ihr Veranstalter</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >:fa3-wrench: Einstellungen</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >Erweiterungen</span>.
Suchen Sie nach der Erweiterung "Kulturpass" und klicken Sie <span class="typo-btn">Aktivieren</span>.
Navigieren Sie anschließend zu <span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Ihr Veranstalter</span> → :fa3-wrench: Einstellungen → Kulturpass:.
Hinterlegen Sie hier den "API Schlüssel" und die "Shop ID" Ihres KulturPass-Shops.
Sie finden den API-Schlüssel im [KulturPass-Backend](https://kulturpass-de.mirakl.net/).
Öffnen Sie den Link und loggen Sie sich ein.
Klicken Sie das Benutzer-Symbol in der oberen, rechten Ecke, <span class="typo-btn">Profil</span> und dann "API Schlüssel".
Sie finden die Shop-ID, indem Sie in der Navigation links "Einstellungen" und dann "Shop" auswählen.
### Verbindung und Konfiguration der Veranstaltung
Jede einzelne Veranstaltung, die Sie über den KulturPass anbieten möchten, benötigt die KulturPass-Erweiterung.
Um diese zu aktivieren, navigieren Sie zu <span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Ihre Veranstaltung</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >:fa3-wrench: Einstellungen</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >Erweiterungen</span> und wechseln Sie zum Tab <span class="typo-btn">Integrationen</span>.
Aktivieren Sie hier das Plugin "KulturPass".
Wenn es sich bei Ihrer Veranstaltung um eine Einzelveranstaltung handelt (keine Veranstaltungsreihe) dann navigieren Sie zu <span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Ihre Veranstaltung</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >:fa3-wrench: Einstellungen</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >KulturPass</span>.
Wenn es sich bei Ihrer Veranstaltung um eine Veranstaltungsreihe handelt, dann navigieren Sie stattdessen zu <span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Ihre Veranstaltung</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >:fa3-calendar: Termine</span> und erstellen oder bearbeiten Sie einen der Termine, die Sie den über KulturPass-Marktplatz anbieten möchten.
Aktivieren Sie das Kontrollkästchen "Diese Veranstaltung über den KulturPass anbieten".
Sobald Sie das getan haben, werden weitere Einstellungen angezeigt.
Geben Sie die notwendigen Informationen ein.
Der KulturPass-Marktplatz verwendet ausschließlich die Informationen, die Sie hier angeben.
Verwenden Sie daher präzise Titel und Beschreibungen.
Klicken Sie dann den <span class="typo-btn">Speichern</span>-Knopf.
Wiederholen Sie diese Schritte für jede Veranstaltung oder jeden Termin innerhalb einer Veranstaltungsreihe, für die Sie den KulturPass nutzen möchten.
Es kann einige Zeit dauern, bis hier vorgenommene Einstellungen im KulturPass-System angezeigt werden.
!!! Note
Der KulturPass-Marktplatz zeigt nicht die gleiche Fülle von Informationen an wie Ihr pretix-Ticketshop.
Wahrscheinlich nutzen Sie für Ihre Veranstaltung oder insbesondere Ihre Termine recht kurze Titel.
Betreiben Sie zum Beispiel ein Schwimmbad, könnte Ihre Veranstaltungsreihe "Freibad Musterstadt" heißen und die einzelnen Termine schlicht "Schwimmen".
Der pretix-Shop zeigt den Namen des Veranstalters und der Veranstaltung bzw. Veranstaltungsreihe sowie weitere Informationen an.
Daher funktioniert diese Benennung hier.
Der Kulturpass-Marktplatz zeigt diese Informationen jedoch nicht an, sondern nur den Titel.
Ein Veranstaltungs- oder Termintitel wie "Schwimmen" ist also nicht informativ genug für den Kulturpass-Marktplatz.
Schreiben Sie daher in pretix in der Kulturpass-Konfiguration in den Feldern "Veranstaltungstitel" und "Veranstaltungsbeschreibung" aussagekräftige Texte, die nicht mit den Veranstaltungen anderer Anbietender verwechselt werden können.
### Anbieten von Produkten über den KulturPass-Marktplatz
Nachdem Sie die KulturPass-Erweiterung aktiviert haben, können Sie einzelne Produkte über den KulturPass-Marktplatz anbieten.
Navigieren Sie zu <span class="sr-only">Navigationspfad</span><span class="typo-navlayer" title="Starten Sie, indem Sie zu diesem Element navigieren">Ihre Veranstaltung</span> :fontawesome-solid-arrow-right: <span class="sr-only">dann</span> <span class="typo-btn" >:fa3-ticket: Produkte</span> und bearbeiten Sie das relevante Produkt.
Öffnen Sie den Tab <span class="typo-btn">Zusätzliche Einstellungen</span> und setzen Sie das Häkchen bei "Das Produkt kann mit dem KulturPass erworben werden".
Wiederholen Sie diese Schritte für jedes Produkt, dass Sie über den KulturPass-Marktplatz anbieten möchten.
Sie können beliebig viele Produkte über den KulturPass-Marktplatz anbieten.
!!! Note
Ihr Angebot wird im KulturPass-Marktplatz immer mit dem höchsten einzelnen Produktpreis gelistet.
Wenn Sie ein Produkt für 100 € über den KulturPass-Marktplatz anbieten, wird Ihr Angebot dort mit 100 € gelistet.
Das gilt sogar dann, wenn alle anderen Produkte in Ihrem Shop z.B. nur 5 € kosten.
Das KulturPass-Guthaben einer kaufenden Person muss mindestens 100 € betragen, damit sie Ihr Angebot in Anspruch nehmen kann.
Die kaufende Person wählt erst mit dem KulturPass-Einlösecode im Wert von 100 € in Ihrem pretix-Shop ein Produkt aus.
Das Restguthaben wird nach dem Kauf automatisch zurückerstattet und dem KulturPass-Konto gutgeschrieben.
### Konfiguration des Marktplatz-Eintrages
Sobald Sie mindestens eine Veranstaltung konfiguriert und live geschaltet haben, übermittelt pretix die Daten automatisch in regelmäßigen Abständen an das KulturPass-System (Mirakl).
Der Export der Produkte und Angebote kann einige Zeit in Anspruch nehmen.
Alle neuen Angebote werden händisch von den Betreibenden der KulturPass-Plattform geprüft, bevor diese sie freigeben.
Außerdem muss eine Synchronisation zwischen dem Hintergrundsystem und der KulturPass-App erfolgen.
pretix hat keinen Einfluss auf die Dauer dieser Prozesse.
Nachdem pretix erstmalig Angebote an das KulturPass-System übermittelt hat, müssen Sie Ihren KulturPass-Shop einmalig freischalten.
Loggen Sie sich hierzu in das [KulturPass-Backend](https://kulturpass-de.mirakl.net/) ein.
## Verwalten von KulturPass-Bestellungen
Sobald Sie Ihr Veranstalterkonto, Ihre Veranstaltung bzw. Termine und Produkte für die Integration mit dem KulturPass-System eingerichtet haben, müssen Sie sich um nichts weiteres kümmern.
pretix übermittelt automatisch Ihre Veranstaltungen, wickelt die Einlösung der Tickets ab und führt die Abrechnung mit dem Hintergrund-System durch.
Die Gelder für mit dem KulturPass bezahlten Tickets erhalten Sie in Form einer Sammelüberweisung von der Stiftung Digitale Chancen auf das Bankkonto, das Sie bei der Einrichtung Ihres KulturPass-Kontos angegeben haben.
In Ihrem [KulturPass-Backend](https://kulturpass-de.mirakl.net/) können Sie über den Menüpunkt "Buchhaltung" Ihre bereits erfolgten und kommenden Auszahlungen betrachten.
!!! Warning
Bearbeiten Sie **niemals** eingehende Bestellungen, Produkte oder Angebote im KulturPass-Backend.
Sie würden damit riskieren, dass die Datenbasis zwischen pretix und dem KulturPass-System divergiert und es zu fehlerhaften Buchungen kommt.
Nehmen Sie Korrekturbuchungen und Änderungen ausschließlich über pretix vor.
Sollte eine händische Änderung notwendig werden, wenden Sie sich bitte an den pretix-Support.
Erstattungen für Stornierungen und Absagen können Sie ebenfalls über das pretix-Backend vornehmen.
Der zurückzuerstattende Betrag wird dem KulturPass-Konto automatisch gutgeschrieben.
!!! Note
Nach Ausgabe eines KulturPass-Einlösecodes kann dieser von der kaufenden Person jederzeit storniert werden.
Das System kann ihn ebenfalls stornieren, wenn er nicht binnen 48 Stunden vollständig eingelöst wurde.
Dies kann zu Fluktuationen im Guthaben führen, das im KulturPass-Backend angezeigt wird.
Auszahlungen erfolgen frühestens 48 Stunden nach der Aufgabe einer KulturPass-Bestellung.
Ihr Guthaben wird daher in der Regel nicht ins Negative gehen.
## Ablauf für kaufende Personen
Für Besuchende Ihres pretix-Shops verhält sich der KulturPass wie eine Zahlungsmethode und wird im Bestellprozess neben Ihren anderen Zahlungsmethoden angeboten.
Wenn sie KulturPass als Zahlungsmethode auswählen, können sie sich dort anmelden oder registrieren und ihr Guthaben erhalten.
KulturPass-Nutzende können ein Angebot einer Veranstaltung auswählen, die via pretix vertrieben wird und erhalten dann innerhalb von 20 Minuten einen Einlösecode und einen Link.
Der Link bringt die Person direkt auf die Seite der betreffenden pretix-Veranstaltung.
Beim Bezahlen schlägt der Shop der kaufenden Person vor, den KulturPass-Einlösecode zu nutzen.
Wenn Artikel gewählt werden, die günstiger als der Wert des Einlösecodes sind, dann wird das Restguthaben automatisch auf das KulturPass-Konto erstattet.
Wenn die Artikel insgesamt teurer sind, dann kann die kaufende Person die Differenz mit einem anderen regulären Zahlungsmittel begleichen.
Einlösecodes, die Kunden nicht binnen 48 Stunden eingelöst werden, werden automatisch storniert und dem KulturPass-Konto wieder gutgeschrieben.
Dieser Mechanismus greift auch, falls eine Veranstaltung in der Zwischenzeit ausverkauft wurde und daher der Einlösecode nicht mehr nutzbar ist.
## Siehe auch
Weitergehende Informationen zum KulturPass finden Sie auch auf der [Webseite des KulturPasses](https://www.kulturpass.de/) sowie im [KulturPass Serviceportal](https://service.kulturpass.de/help/).
Then, create a file with the extension .de.md in the same directory, which only contains the title and the include command. Do not put the hint regarding the language into the German docs file.
Indicating pretix editions#
Mark sections that are specific to certain pretix editions the following way:
<span class="mdx-badge mdx-badge--hosted" title="Dieser Abschnitt bezieht sich auf unser Cloud-Angebot pretix Hosted."><span class="mdx-badge__icon">:material-cloud:</span><span class="mdx-badge__text">pretix Hosted</span></span>
<span class="mdx-badge mdx-badge--community" title="Dieser Abschnitt bezieht sich auf die Open-Source-Variante von pretix zum Einsatz auf Ihrem eigenen Server."><span class="mdx-badge__icon">:material-heart-outline:</span><span class="mdx-badge__text">pretix Community</span></span>
<span class="mdx-badge mdx-badge--enterprise" title="Dieser Abschnitt bezieht sich auf die kommerzielle Variante von pretix zum Einsatz auf Ihrem eigenen Server."><span class="mdx-badge__icon">:material-star:</span><span class="mdx-badge__text">pretix Enterprise</span></span>
You can use the same formatting for specific version updates.