GitHub » Formattare il markdown per un README ordinato

· 7 min lettura
GitHub » Formattare il markdown per un README ordinato

Quando si finisce di scrivere un progetto e si decide di caricarlo sulla piattaforma GitHub, si deve pensare ad una buona presentazione per il progetto (o “repository”), per essere precisi.

Invece del solito testo piatto, minimalista e semplice come “questo programma fa questa cosa. Per saperne di più, digita --help“, perché non butti giù una vera e propria introduzione per guidare gli utenti alla scoperta del tuo progetto?

Per iniziare a scrivere subito il README, si dovrà selezionare l’apposita spunta “Initialize this repository with a README“.

Una volta inizializzato il README di GitHub, verrà copiato il nome della repository e la descrizione breve che avete fornito (se fornita).

L’icona della matita sarà il collegamento che reindirizzerà ad un editor del file.

GitHub supporta due tipi di linguaggi:

  • Testo semplice
  • Markdown (simil-HTML, semplificato per chi non ha dimestichezza con i tag HTML)

Titoli e sottotitoli

Salterà sicuramente all’occhio che la prima linea, quella che riporta il nome della repository, è preceduta da un #. Come conseguenza, nella preview del file, la riga sarà visualizzata più grande della riga successiva.

Quel cancelletto, infatti, è l’equivalente di <H1>, il tag HTML che identifica i titoli.

Aggiungendo un secondo cancelletto, il titolo sarà più piccolo, come il tag <H2>

# Nome-Repository
Repository di prova

Da qui si può continuare con 3, 4, anche 5 cancelletti, tutti correlati ai relativi tag <H3>, <H4> e <H5>.

# Titolo H1
## Titolo H2
### Titolo H3
#### Titolo H4
##### Titolo H5

Grassetto

Per evidenziare una parte di testo si usa l’equivalente del tag <b> (bold), ossia un doppio asterisco ** prima e dopo il testo da evidenziare.

È possibile usare anche un doppio underscore __ al posto degli asterischi.

**Testo in grassetto** fatto con due asterischi.
__Testo in grassetto__ fatto con due underscore.

Corsivo

Il corsivo è simile al grassetto, ma si usa un solo asterisco * o underscore _ invece che due.

*Testo in corsivo* fatto con un asterisco.
_Testo in corsivo_ fatto con un underscore.

Il motivo del doppio simbolo sta nel fatto che è possibile mischiare gli stili di testo.

**Testo in grassetto ma che contiene una parte di _testo in corsivo_ per mischiare gli stili**
*Testo in corsivo ma che contiene una parte di __testo in grassetto__ per mischiare gli stili*

Testo barrato

Per il testo barrato si usa il carattere tilde ~, non presente nella tastiera italiana, ma ottenibile con la combinazione ALT + 126.

Benvenuti nella nostra ~~setta demoniaca~~ sala riunioni.

Caratteri di escape

Se gli asterischi e gli underscore sono riconosciuti come markdown, questo vuol dire che per visualizzare asterischi e underscore non c’è modo?

No!

Per visualizzare i caratteri considerati “speciali” all’interno del documento, si usa il backslash \.

Per inserire un testo in corsivo bisogna scriverlo fra underscore, \_in questo modo\_.

Altrimenti, si possono usare gli asterischi, \*in questo modo\*.

Per il grassetto è uguale, \*\*bastano due asterischi prima e due dopo\*\*.

Idem per il corsivo, \_\_nulla di diverso\_\_.

Il carattere di escape backslash è valido per visualizzare senza essere interpretati i seguenti caratteri:

` accento grave
* asterisco
_ underscore
{} parentesi graffe
[] parentesi quadre
() parentesi tonde
# cancelletto / hashtag
+ più
- meno / trattino
. punto
! punto esclamativo

Collegamenti

Riferimenti a risorse esterne possono essere un buon appiglio per fonti o guide già scritte. Per inserire un collegamento internet si può semplicemente incollare il suo contenuto per intero, venendo automaticamente riconosciuto dalla piattaforma:

https://mceyes.me

Altrimenti si potrà anche inserire un così detto hyperlink, con un testo descrittivo, che spesso occuperà meno spazio del link effettivo.

[Visita il mio sito!](http://mceyes.me)

Liste

Numerate

Per una lista numerata (1, 2, 3…) si usano, prevedibilmente, numeri consequenziali seguiti da un punto, uno per riga.

1. Primo elemento della lista
2. Secondo elemento della lista
3. Avete capito l'andazzo
4. Andando avanti...

Per nidificare la lista (per indicare sotto-elementi, per esempio), si precedono gli elementi della sotto-lista con una tabulazione (TAB).

1. Primo elemento della lista
2. Secondo elemento della lista, che comprende sotto-elementi
    1. Primo sotto-elemento
    2. Secondo sotto-elemento
3. Terzo elemento della lista principale

Puntate

Un elenco puntato si ottiene utilizzando un solo asterisco (invece di inserirne uno anche a fine frase) e separare, come gli elementi numerati, un elemento per riga.

* Primo elemento della lista
* Secondo elemento della lista
* Terzo elemento della lista principale

Anche gli elenchi puntati possono essere nidificati.

* Primo elemento della lista
* Secondo elemento della lista, che comprende sotto-elementi
    * Primo sotto-elemento in ordine
    * Secondo sotto-elemento in ordine
* Terzo elemento della lista principale

Come grassetto e corsivo, le liste possono essere mischiate fra di loro.

* Primo elemento della lista
* Secondo elemento della lista, che comprende sotto-elementi
    1. Primo sottoelemento in ordine
    2. Secondo sottoelemento in ordine
* Terzo elemento della lista principale

Citazioni

Nel caso si volessero inserire citazioni, GitHub mette a disposizione una formattazione che potrà aiutare.

Come dice il saggio:
> Meglio un giorno da leone che mille da cento

Emoji

Perché no, un’emoji può fare la differenza in quanto appeal del vostro README.

What's cooler than being cool? 😎

Per integrare un’emoji nel proprio markdown, basti inserire l’identificativo dell’emoji desiderata tra due doppi punti :.

Aggiunto supporto a CPU quantistiche :sparkles:
Finalmente siano online :metal:

L’elenco delle emoji supportate da GitHub è disponibile qui:

Emoji Cheat Sheet
Emoji codes used by GitHub, Basecamp, Slack and other services. Searchable. With emoji meanings.

Checklist o “lista della spesa”

Nel caso si abbia una timeline o una lista di TODO, si possono semplicemente “spuntare” le opzioni di una lista man mano che esse vengono fatte, una feature viene implementata o un traguardo viene raggiunto con la seguente sintassi:

- [ ] Aggiunti meme nello splash screen
- [x] Caricata backdoor nella piattaforma
- [ ] Licenziato il vecchio sviluppatore
- [x] Aggiunti bug da correggere nella prossima release

Codice sorgente

Non poteva mancare il codice sorgente! Dopotutto parliamo di GitHub, piattaforma PER codici sorgenti, quindi ecco qui il markdown per visualizzare codice sorgente all’interno del vostro README:

Purtroppo serve un carattere che non è compreso nella tastiera italiana, ossia l’accento grave `, presente nella tastiera inglese premendo il tasto a sinistra del numero 1.

Alternativamente, si può scrivere il carattere necessario da una tastiera italiana con la combinazione ALT + 96.

Per inserire del codice all’interno del documento, si inizia il markdown con tre accenti gravi, seguito dal codice e, infine, altri tre accenti gravi per chiudere il markdown.

```
print("Hello World!")
exit
```

Per evidenziare le parti di codice che compongono la sintassi, bisognerà aggiungere il nome del linguaggio di cui si vuole riconoscere la sintassi dopo il primo gruppo di accenti gravi. Terminato il codice, si dovrà chiudere il markdown con altri tre accenti gravi, come precedentemente.

```c++
using namespace std;
int main()
{
	cout<<"Hello world!"<<endl;
}
```

Di seguito l’elenco di linguaggi riconosciuti da GitHub:

actionscript3
apache
applescript
asp
brainfuck
c
cfm
clojure
cmake
coffee-script
C++
cs
csharp
css
csv
bash
diff
elixir
erb - HTML + Embedded Ruby
go
haml
http
java
javascript
json
jsx
less
lolcode
make - Makefile
markdown
matlab
nginx
objectivec
pascal
PHP
Perl
python
profile - python profiler output
rust
salt
Shell scripting (BASH, ZSH, ASH...)
sql
scss
sql
svg
swift
rb, jruby, ruby - Ruby
smalltalk
vim, viml - Vim Script
volt
vhdl
vue
xml
yaml

Codice inline

Per inserire parti di codice all’interno di una riga di testo, senza interrompere la frase, si fa uso nuovamente dell’accento grave `. Attenzione ad inserire l’accento solamente prima e dopo la parola desiderata.

Cliccare il tasto `WIN` per aprire il menu start

Immagini

Le immagini vengono automaticamente riconosciute dalla piattaforma, perciò basterà copiare il formato dei links, precedendo il testo con un punto esclamativo !, facendo puntare il documento ad una risorsa immagine, invece che un collegamento internet.

![Logo](https://mceyes.me/content/images/2021/10/github-cover.jpg)

Tabelle

Per le tabelle bisogna lavorare di immaginazione, poiché si dovrà letteralmente disegnare un separatore fra le celle e un separatore per l’header con i simboli meno - e pipe |.

Componente | Scopo
---- | ----
Processore | Calcolare
Dissipatore | Dissipare

Ogni volta che supporti il blog

Tyrion educa suo nipote Joffrey

Supporta anche tu la cultura della punizione corporale contro i nipoti