Skip to content

Commit

Permalink
docs(contributing): Homogenize format & indent of code blocks
Browse files Browse the repository at this point in the history
- Format using fenced style.
- Well indent in those placed inside list enumerations.
- Simulate `Good` - `Bad` monospace double colon indent inside each one.

- Examples highlighting as `text-plain`. The `md, markdown` style doesn't work very well since blocks has mixed syntax.
- `check_urls` code block highlighted as `properties` style (key-value pair).

Solves markdownlint rules:
- MD040/fenced-code-language: Fenced code blocks should have a language specified
- MD046/code-block-style: Code block style [Expected: indented; Actual: fenced]
  • Loading branch information
davorpa committed Nov 4, 2021
1 parent 31c776c commit f9dc719
Show file tree
Hide file tree
Showing 14 changed files with 587 additions and 563 deletions.
80 changes: 41 additions & 39 deletions CONTRIBUTING-de.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,63 +73,65 @@ Folgende Formatierungsregeln sollten eingehalten werden:

Beispiel:

[...]
* [Ein tolles Buch](http://example.com/example.html)
(Leerzeile)
(Leerzeile)
### Beispiel
(Leerzeile)
* [Noch ein tolles Buch](http://example.com/book.html)
* [Ein anderes Buch](http://example.com/other.html)
```text
[...]
* [Ein tolles Buch](http://example.com/example.html)
(Leerzeile)
(Leerzeile)
### Beispiel
(Leerzeile)
* [Noch ein tolles Buch](http://example.com/book.html)
* [Ein anderes Buch](http://example.com/other.html)
```

- Keine Leerzeichen zwischen `]` und `(` einfügen:

```
FALSCH : * [Noch ein tolles Buch] (http://example.com/book.html)
RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html)
```
```text
FALSCH : * [Noch ein tolles Buch] (http://example.com/book.html)
RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html)
```

- Wenn Du den Autor nennst, nutze ` - ` (einen mit Leerzeichen eingefassten Gedankenstrich):

```
FALSCH : * [Noch ein tolles Buch](http://example.com/book.html)- John Doe
RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html) - John Doe
```
```text
FALSCH : * [Noch ein tolles Buch](http://example.com/book.html)- John Doe
RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html) - John Doe
```

- Füge ein einzelnes Leerzeichen zwischen dem Link und seinem Dateiformat ein:

```
FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)(PDF)
RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) (PDF)
```
```text
FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)(PDF)
RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) (PDF)
```

- Der Autor wird vor dem Format genannt:

```
FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)- (PDF) Jane Roe
RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) - Jane Roe (PDF)
```
```text
FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)- (PDF) Jane Roe
RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) - Jane Roe (PDF)
```

- Verschiedene Formate:

```
FALSCH : * [Noch ein tolles Buch](http://example.com/)- John Doe (HTML)
FALSCH : * [Noch ein tolles Buch](https://downloads.example.org/book.html)- John Doe (download site)
RICHTIG: * [Noch ein tolles Buch](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```
```text
FALSCH : * [Noch ein tolles Buch](http://example.com/)- John Doe (HTML)
FALSCH : * [Noch ein tolles Buch](https://downloads.example.org/book.html)- John Doe (download site)
RICHTIG: * [Noch ein tolles Buch](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```

- Nenne das Jahr der Veröffentlichung im Titel bei älteren Publikationen:

```
FALSCH : * [Ein sehr tolles Buch](https://example.org/book.html) - Jane Roe - 1970
RICHTIG: * [Ein sehr tolles Buch (1970)](https://example.org/book.html) - Jane Roe
```
```text
FALSCH : * [Ein sehr tolles Buch](https://example.org/book.html) - Jane Roe - 1970
RICHTIG: * [Ein sehr tolles Buch (1970)](https://example.org/book.html) - Jane Roe
```

- <a name="in_process"></a>Bücher in Bearbeitung:

```
RICHTIG: * [Wird bald ein tolles Buch sein](http://example.com/book2.html) - John Doe (HTML) (:construction: *in Bearbeitung*)
```
```text
RICHTIG: * [Wird bald ein tolles Buch sein](http://example.com/book2.html) - John Doe (HTML) (:construction: *in Bearbeitung*)
```


### Hinweise
Expand Down Expand Up @@ -228,9 +230,9 @@ Wenn etwas ausgedruckt werden kann, ohne dass es seinen Nutzen verliert, ist es
- Die URLs werden über [awesome_bot](https://github.com/dkhamsing/awesome_bot) validiert.
- Um die URL-Validierung auszulösen, kann ein Commit abgeschickt werden, der `check_urls=file_to_check` enthält:

```
check_urls=free-programming-books.md free-programming-books-en.md
```
```properties
check_urls=free-programming-books.md free-programming-books-de.md
```

- Man kann mehr als eine zu überprüfende Datei angeben, wobei die Einträge mit einem einzelnen Leerzeichen getrennt werden.
- Bei Angabe von mehr als einer Datei basiert das Ergebnis des Builds auf dem Ergebnis der letzten geprüften Datei. Du solltest Dir darüber im Klaren sein, dass dies zu gültigen Builds führen kann und daher das Build Protokoll am Ende des Pull Request durch Klick auf "Show all checks" -> "Details" genau geprüft werden sollte.
86 changes: 44 additions & 42 deletions CONTRIBUTING-el.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,69 +79,71 @@

Παράδειγμα:

[...]
* [Ένα Φοβερό Βιβλίο](http://example.com/example.html)
(κενή γραμμή)
(κενή γραμμή)
### Παράδειγμα
(κενή γραμμή)
* [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)
* [Κάποιο Άλλο Βιβλίο](http://example.com/other.html)
```text
[...]
* [Ένα Φοβερό Βιβλίο](http://example.com/example.html)
(κενή γραμμή)
(κενή γραμμή)
### Παράδειγμα
(κενή γραμμή)
* [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)
* [Κάποιο Άλλο Βιβλίο](http://example.com/other.html)
```

- Μη βάζετε κενό μεταξύ `]` και `(`:

```
ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο] (http://example.com/book.html)
ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)
```
```text
ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο] (http://example.com/book.html)
ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)
```

- Αν συμπεριλαμβάνετε συγγραφέα, χρησιμοποιήστε ` - ` (μια παύλα που περιβάλλεται από κενά):

```
ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)- John Doe
ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) - John Doe
```
```text
ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)- John Doe
ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) - John Doe
```

- Εισάγετε ένα κενό μεταξύ του συνδέσμου και του format του:

```
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)(PDF)
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) (PDF)
```
```text
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)(PDF)
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) (PDF)
```

- Ο συγγραφέας μπαίνει πριν το format

```
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)- (PDF) Jane Roe
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) - Jane Roe (PDF)
```
```text
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)- (PDF) Jane Roe
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) - Jane Roe (PDF)
```

- Πολλαπλά formats:

```
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/)- John Doe (HTML)
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://downloads.example.org/book.html)- John Doe (download site)
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```
```text
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/)- John Doe (HTML)
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://downloads.example.org/book.html)- John Doe (download site)
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```

- Συμπεριλαμβάνετε χρονιά δημοσιεύσης στον τίτλο για παλαιότερα βιβλία:

```
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.html) - Jane Roe - 1970
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο (1970)](https://example.org/book.html) - Jane Roe
```
```text
ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.html) - Jane Roe - 1970
ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο (1970)](https://example.org/book.html) - Jane Roe
```

- <a name="in_process"></a>Βιβλία σε εξέλιξη:

```
ΚΑΛΟ: * [Θα Είναι Σύντομα Ένα Φοβερό Βιβλίο](http://example.com/book2.html) - John Doe (HTML) (:construction: *σε εξέλιξη*)
```
```text
ΚΑΛΟ: * [Θα Είναι Σύντομα Ένα Φοβερό Βιβλίο](http://example.com/book2.html) - John Doe (HTML) (:construction: *σε εξέλιξη*)
```

- <a name="archived"></a>Αρχειοθετημένοι σύνδεσμοι:

```
ΚΑΛΟ: * [Ένα Ενδιαφέρον Way-backed Βιβλίο](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: αρχειοθετημένο)*
```
```text
ΚΑΛΟ: * [Ένα Ενδιαφέρον Way-backed Βιβλίο](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: αρχειοθετημένο)*
```


<a name="notes"></a>
Expand Down Expand Up @@ -243,9 +245,9 @@
- Η επικύρωση των URL χρησιμοποιεί το [awesome_bot](https://github.com/dkhamsing/awesome_bot)
- Για να ενεργοποιήσετε την επικύρωση του URL, κάντε push ένα commit που περιέχει ένα μήνυμα στο οποίο υπάρχει το `check_urls=file_to_check`:

```
check_urls=free-programming-books.md free-programming-books-en.md
```
```properties
check_urls=free-programming-books.md free-programming-books-el.md
```

- Μπορείτε να προσδιορίσετε πάνω από ένα αρχείο για έλεγχο, χρησιμοποιώντας ένα κενό για να ξεχωρίσετε κάθε καταχώρηση.
- Αν προσδιορίσετε πάνω από ένα αρχείο, τα αποτελέσματα του build βασίζονται στα αποτελέσματα του τελευταίου αρχείου που ελέγχθηκε. Θα πρέπει να γνωρίζετε ότι ενδέχεται να πάρετε επικυρωμένα builds εξαιτίας αυτού οπότε να είστε σίγουροι ότι επιβλέπετε το αρχείο του build στο τέλος του pull request πατώντας στο "Show all checks" -> "Details".
84 changes: 43 additions & 41 deletions CONTRIBUTING-es.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,69 +79,71 @@ La idea es tener:

Ejemplo:

[...]
* [Un libro increíble](http://example.com/example.html)
(línea en blanco)
(línea en blanco)
### Sección de ejemplo
(línea en blanco)
* [Otro libro fascinante](http://example.com/book.html)
* [Otro libro más](http://example.com/other.html)
```text
[...]
* [Un libro increíble](http://example.com/example.html)
(línea en blanco)
(línea en blanco)
### Sección de ejemplo
(línea en blanco)
* [Otro libro fascinante](http://example.com/book.html)
* [Otro libro más](http://example.com/other.html)
```

- Omita los espacios entre `]` y `(`:

```
INCORRECTO : * [Otro libro fascinante] (http://example.com/book.html)
CORRECTO : * [Otro libro fascinante](http://example.com/book.html)
```
```text
INCORRECTO: * [Otro libro fascinante] (http://example.com/book.html)
CORRECTO : * [Otro libro fascinante](http://example.com/book.html)
```

- Si en el registro decide incluir al autor, emplee ` - ` (un guión rodeado de espacios simples) como separador:

```
INCORRECTO : * [Un libro sencillamente fabuloso](http://example.com/book.html)- John Doe
CORRECTO : * [Un libro sencillamente fabuloso](http://example.com/book.html) - John Doe
```
```text
INCORRECTO: * [Un libro sencillamente fabuloso](http://example.com/book.html)- John Doe
CORRECTO : * [Un libro sencillamente fabuloso](http://example.com/book.html) - John Doe
```

- Ponga un solo espacio entre el enlace al contenido y su formato:

```
INCORRECTO : * [Un libro muy interesante](https://example.org/book.pdf)(PDF)
CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) (PDF)
```
```text
INCORRECTO: * [Un libro muy interesante](https://example.org/book.pdf)(PDF)
CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) (PDF)
```

- El autor se antepone al formato:

```
INCORRECTO : * [Un libro muy interesante](https://example.org/book.pdf)- (PDF) Jane Roe
CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) - Jane Roe (PDF)
```
```text
INCORRECTO: * [Un libro muy interesante](https://example.org/book.pdf)- (PDF) Jane Roe
CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) - Jane Roe (PDF)
```

- Múltiples formatos:

```
INCORRECTO : * [Otro libro interesante](http://example.com/) - John Doe (HTML)
INCORRECTO : * [Otro libro interesante](https://downloads.example.org/book.html) - John Doe (sitio de descarga)
CORRECTO : * [Otro libro interesante](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```
```text
INCORRECTO: * [Otro libro interesante](http://example.com/) - John Doe (HTML)
INCORRECTO: * [Otro libro interesante](https://downloads.example.org/book.html) - John Doe (sitio de descarga)
CORRECTO : * [Otro libro interesante](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```

- Incluya el año de publicación como parte del título de los libros más antiguos:

```
INCORRECTO : * [Un libro bastante especial](https://example.org/book.html) - Jane Roe - 1970
CORRECTO : * [Un libro bastante especial (1970)](https://example.org/book.html) - Jane Roe
```
```text
INCORRECTO: * [Un libro bastante especial](https://example.org/book.html) - Jane Roe - 1970
CORRECTO : * [Un libro bastante especial (1970)](https://example.org/book.html) - Jane Roe
```

- <a name="in_process"></a>Libros en proceso / no acabados aún:

```
CORRECTO: * [A punto de ser un libro fascinante](http://example.com/book2.html) - John Doe (HTML) (:construction: *en proceso*)
```
```text
CORRECTO : * [A punto de ser un libro fascinante](http://example.com/book2.html) - John Doe (HTML) (:construction: *en proceso*)
```

- <a name="archived"></a>Enlaces archivados:

```
CORRECTO: * [Un recurso recuperado a partir de su línea de tiempo](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archivado)*
```
```text
CORRECTO : * [Un recurso recuperado a partir de su línea de tiempo](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archivado)*
```


<a name="notes"></a>
Expand Down Expand Up @@ -252,8 +254,8 @@ Si es posible imprimirlo y conservar su esencia, no es un Tutorial Interactivo.
- La validación de URLs se realiza mediante [awesome_bot](https://github.com/dkhamsing/awesome_bot)
- Para activar esta validación de URL, envíe un commit que incluya como mensaje de confirmación `check_urls=fichero_a_comprobar`:

```
check_urls=free-programming-books.md free-programming-books-en.md
```properties
check_urls=free-programming-books.md free-programming-books-es.md
```

- Es posible especificar más de un fichero a comprobar. Simplemente use un espacio para separar cada entrada.
Expand Down
Loading

1 comment on commit f9dc719

@davorpa
Copy link
Owner Author

@davorpa davorpa commented on f9dc719 Nov 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Completed by a2d758b

Please sign in to comment.