Skip to content

Latest commit

 

History

History
92 lines (61 loc) · 3 KB

CONTRIBUTING.md

File metadata and controls

92 lines (61 loc) · 3 KB

Mitwirken am MM-Handbuch

Eine Mitarbeit am MM-Handbuch ist herzlich willkommen. Die Daten werden hier auf Github verwaltet und nach Freigabe automatisch bei Readthedocs zu einer HTML-Seite als MM-Handbuch konvertiert.

Die einfachste Art am Handbuch mitzuarbeiten ist über ein Github-Account mit dem man Änderungen oder komplett neue Seiten als "Pull-Request" (PR) anfügen kann.

Bei kleineren Änderungen der im Handbuch angezeigte Seite kann man dem Link oben rechts "Auf GitHub bearbeiten" folgen und den Text direkt im Browser anpassen sowie einen PR erstellen.

Bei umfangreicheren Änderungen bzw. komplett neuen Artikeln ist es zu empfehlen, einen Fork des Handbuchs zu erstellen und den Clone lokal zu bearbeiten. Gern mal einen Blick in eine bestehende Datei werfen - damit sieht man den Aufbau und Formatierungen meist recht gut.

Alternativ kann man auch seinen Artikel an [email protected] senden.

Die Texte sind in reStructuredText ausgezeichnet, welches ähnlich wie Markdown aufgebaut ist. Die Konvertierung auf der Seite Readthedocs übernimmt das Tool "Sphinx". Wer möchte, kann Sphinx auch lokal installieren und das gesamte Handbuch in das gewünschte Format wie HTML, EPUB, PDF usw. konvertieren.

Hinweise zum Schreiben der Texte

Der Text sollte in einer neutralen Ansprache des Lesers erfolgen - üblicherweise mit "man".

Bitte Schachtelsätze vermeiden und längere Absätze in logische Blöcke unterteilen.

Nach dem Schreiben eines neuen Artikels, die Anleitung selbst nochmal "nachklicken" - damit findet man Lücken und Fehler im Ablauf.

Überschriften:

H1 Überschrift
==============

H2 Überschrift
--------------

H3 Überschrift
..............

Bilder

Bilder sind im Ordner _img/screenshots/..

Im Text per "Ersetzungstoken" einfügen z.B. Lorem ipsum |img_multi-textfilter_01| bla bla...

und unten auf der Seite

.. |img_multi-textfilter_01| image:: /_img/screenshots/cookbook/filter/multi-textfilter_01.jpg

Code

Inline: als :code:`das ist mein code`

Block:

.. code-block:: php
   :linenos:

   // Redirect if data empty.
   if (!count($this->data)) {
       $pageId  = 42; // Page id 
       $page    = \Contao\PageModel::findByPK($pageId);
       $pageURL = $page->getFrontendUrl();
       \Contao\Controller::redirect($pageURL);
   }

Bitte beachten, dass die erste Einrückung drei Leerzeichen sind. Bei der Angabe "code-block" sind auch andere Angaben wie css, yaml, xml möglich.

Verlinkungen

oberhalb der zu verlinkenden Überschrift .. _rst_features:

als Link einfügen z.B. per :ref:`rst_features`

oder mit eigenem Linktext :ref:`Neue Funktionen <rst_features>`

externe Verlinkungen: `Contao <https://www.contao.org>`_ offensichtlich gibt es keine Möglichkeit das Attribut "target" anzugeben...