La prima volta che un mio README ha attraversato mille righe, ho fatto quello che fanno tutti: ho fatto scorrere Poi ne ho fatto un altro giro Da qualche parte intorno al quarto passaggio cercando il & quot;Deployment" sezione, ho rinunciato e ho iniziato a scrivere a mano un sommario nella parte superiore del file. Ha funzionato finché non ho rinominato un'intestazione, ho dimenticato di aggiornare il collegamento e ho spedito un README dove & quot;Configurazione" non ha puntato nulla Un collegamento in pagina interrotto nella tua documentazione è una piccola cosa, ma è il tipo di piccola cosa che dice a un lettore che nessuno si preoccupa del negozio.
Costruisco [Toolz.dev] (/, una raccolta di utility per sviluppatori basate su browser, e mantengo molto Markdown: guide agli strumenti, file README, specifiche interne e i documenti che stai leggendo in questo momento Un sommario che devo mantenere a mano è un sommario che alla fine mentirà Così ho costruito il Markdown TOC Generatore per fare la parte noiosa correttamente ogni volta, e questa guida è tutto ciò che ho imparato sui collegamenti di ancoraggio durante la sua costruzione.
tl; dr: Un indice Markdown è un elenco annidato di collegamenti che saltano alle intestazioni sulla stessa pagina I collegamenti funzionano perché ogni intestazione ottiene un id di ancoraggio automatico e il slug che GitHub assegna segue una regola specifica: minuscolo il testo, punteggiatura a goccia diversa dai trattini e trasforma gli spazi in trattini Incolla il tuo Markdown nel generatore, scegli quali livelli di intestazione includere e copia l'elenco Lo strumento calcola i rendering esatti slugs GitHub, incluso il
-1suffisso per intestazioni duplicate, quindi nulla si rompe quando lo incolli indietro.
Che cosa è un indice Markdown?
Un sommario in Markdown non è una sintassi speciale. 02 non definisce tale costrutto, e nemmeno GitHub Flavored Markdown È un elenco ordinario in cui ogni elemento è un collegamento e ogni collegamento punta a un ancoraggio all'interno dello stesso documento Quando un renderer Markdown come GitHub trasforma un'intestazione in HTML, dà anche a quell'intestazione un id attributo. Un'intestazione scritta come ## Getting Started diventa approssimativo <h2 id="getting-started">Getting Started</h2>. Una volta che quell'id esiste, un collegamento scritto come [Getting Started](#getting-started) scorre la pagina ad esso.
Quindi un sommario è solo una raccolta di quei collegamenti, rientrati per rispecchiare la gerarchia delle intestazioni:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
L'intero trucco vive in una parola di quell'esempio: l'ancora Sbaglia l'ancora e il collegamento fallisce silenziosamente, scorrendo da nessuna parte Azzeccalo e il blocco dei contenuti funziona su GitHub, nella maggior parte dei generatori di siti statici e all'interno di piattaforme di documentazione che seguono la stessa convenzione La parte difficile è non scrivere l'elenco La parte difficile è prevedere l'id esatto che ogni renderer assegnerà, motivo per cui farlo a mano è un gioco perdente su qualsiasi documento che cambia.
Come vengono effettivamente generate le ancore di rotta?
GitHub's slug algorithm è deterministico e vale la pena memorizzarlo, perché una volta che lo conosci puoi prevedere ogni ancoraggio nella pagina I passaggi, nell'ordine, sono: convertire il testo dell'intestazione in minuscolo, rimuovere qualsiasi carattere che non sia una lettera, un numero, uno spazio o un trattino, e quindi sostituire ogni spazio con un trattino Questa è l'intera regola.
Le conseguenze sono dove le persone inciampano Considera un titolo come ## Set Up & Config. Il rivestimento inferiore dà set up & config. Rimuovendo la e commerciale (ma lasciando gli spazi attorno ad essa) si ottiene set up config con due spazi dove il & una volta lo era. Trasformare gli spazi in trattini produce set-up--config, con un doppio trattino Quel doppio trattino sembra un errore, ma è esattamente ciò che rende GitHub, quindi è esattamente ciò di cui il tuo link ha bisogno Uno strumento che & quot; pulisce & quot; il doppio trattino produrrebbe un collegamento che non si risolve.
Le intestazioni pesanti per la punteggiatura crollano più di quanto ti aspetti. ## C++ Guide diventa c-guide, perché entrambi i segni più vengono spogliati e lo spazio avanzato diventa un unico trattino. ## What's New? diventa whats-new, perché l'apostrofo e il punto interrogativo svaniscono Emoji e la maggior parte dei simboli scompaiono interamente Il Markdown TOC Generatore applica questo carattere di regola per il carattere in modo che slug ti mostri che l'id che GitHub costruirà, senza alcuna ipotesi coinvolta.
Cosa succede quando due rubriche sono uguali?
I documenti ripetono le intestazioni Un registro delle modifiche potrebbe avere tre sezioni tutte intitolate ### Fixed. Se ognuno di loro producesse il slug fixed, funzionerebbe solo il primo link GitHub risolve questo problema numerando i duplicati: il primo Fixed ghermire fixed, il secondo ottiene fixed-1, il terzo ottiene fixed-2, e così via in ordine di documento Il suffisso è aggiunto dopo la base slug con un trattino.
Questo è uno dei motivi più comuni per cui un sommario scritto a mano va fuori sincronia. Aggiungi una seconda sezione con un nome che hai già usato, l'ancora diventa silenziosamente -1, e il tuo vecchio collegamento ora punta nel posto sbagliato o da nessuna parte Il generatore traccia ogni slug che ha emesso e applica lo stesso suffisso numerico, quindi le intestazioni ripetute si collegano all'occorrenza giusta.
Che tipo di intestazioni legge lo strumento?
Markdown ha due stili di intestazione e un generatore completo deve leggerli entrambi. Quello comune è ATX, dove una riga inizia da uno a sei # caratteri seguiti dal testo dell'intestazione Il conteggio degli hash è il livello, quindi # è un H1 e ###### è un H6. Il secondo stile è Setext, dove una riga di testo è sottolineata sulla riga successiva con segni uguali per un H1 o trattini per un H2:
Document Title
==============
A Section
---------
Entrambi gli stili producono intestazioni con id di ancoraggio, quindi entrambi appartengono a un sommario La parte complicata con Setext è dire una vera intestazione sottolineata a parte una regola orizzontale, perché una linea di trattini può significare entrambi La regola utilizzata dal generatore è che una sottolineatura del trattino conta come intestazione solo quando la riga direttamente sopra di essa è il normale testo del paragrafo, non una riga vuota, un elemento di elenco, una virgoletta a blocchi o un altro costrutto a blocchi. UN --- sedersi da solo con linee bianche attorno è una pausa tematica e viene correttamente ignorato.
C'è un'altra categoria da gestire, ed è quella che rovina silenziosamente gli strumenti ingenui: intestazioni all'interno del codice Se il tuo documento contiene un blocco di codice recintato che mostra i comandi della shell, alcune di quelle righe inizieranno con # come commenti Quelle non sono intestazioni, e non devono mai comparire nei contenuti Il generatore traccia blocchi di codice recintati (quelli delimitati da tripli backtick o tripli tilde) e ne salta uno qualsiasi # linea al loro interno Un commento shell come # install dependencies in un esempio rimane dove appartiene, nell'esempio.
Come faccio a controllare la profondità del sommario?
Un sommario che elenca ogni intestazione fino a H6 non è un sommario, è una seconda copia del documento La maggior parte dei README legge meglio quando i contenuti coprono solo H2 e H3, dando ai lettori le sezioni principali e i loro figli più prossimi senza annegarli in dettaglio Il generatore ti consente di impostare un livello minimo e uno massimo e include solo le intestazioni che rientrano in quell'intervallo.
Il comportamento sottile qui è il rientro. Se includi da H2 a H4, la direzione più superficiale che hai mantenuto è un H2 e dovrebbe trovarsi a filo contro il margine sinistro anziché dentellato come se un H1 invisibile fosse sopra di esso. Il generatore misura la profondità di nidificazione rispetto alla direzione più bassa che effettivamente include, quindi un blocco di contenuto che inizia da H2 inizia senza rientro. Questa è la differenza tra un elenco che sembra intenzionale e uno che sembra aver perso la sua prima colonna.
Si arriva anche a scegliere il marcatore di elenco Un elenco non ordinato utilizza un punto elenco per ogni voce, che è il look convenzionale per un README Un elenco ordinato numera le voci, e il generatore riavvia il conteggio all'interno di ogni livello di annidamento in modo che un contorno numerato legga correttamente anziché contare direttamente da uno a cinquanta Il rientro può essere di due spazi, quattro spazi o una scheda, a seconda di ciò che il resto del documento utilizza.
E le intestazioni accentate e non latine?
Non tutte le intestazioni sono in inglese semplice e la regola slug deve farcela. GitHub conserva le lettere di altri alfabeti anziché rimuoverle, quindi un'intestazione simile ## Configuración mantiene i suoi caratteri accentati e diventa configuración, e un'intestazione in cirillico o greco mantiene anche quelle lettere Ciò che viene rimosso è la punteggiatura e i simboli, non le lettere, indipendentemente dallo script Il generatore segue lo stesso principio trattando qualsiasi lettera o cifra Unicode come un carattere slug valido, quindi un documento multilingue produce ancore che corrispondono a ciò che GitHub rende piuttosto che una fila di collegamenti vuoti.
Questo conta più di quanto appaia per la prima volta I team che scrivono documentazione in spagnolo, tedesco o giapponese spesso scoprono che gli strumenti ingenui slug mangano le loro intestazioni in ancore inutilizzabili, perché quegli strumenti assumono ASCII Se i tuoi link non hanno mai puntato nulla su un README tradotto, un slug che ha silenziosamente scartato le lettere non ASCII è quasi certamente il motivo. Generare il blocco dei contenuti con uno strumento consapevole di Unicode rimuove l'intera classe di link interrotti e significa che lo stesso documento può contenere intestazioni in più di una lingua senza che nessuna di esse perda le proprie ancore.
Quando devo utilizzare un TOC generato rispetto a uno automatico?
Alcune piattaforme costruiscono per te un sommario GitLab supporta un [[_TOC_]] token, alcuni wiki iniettano una casella di contenuto automaticamente e framework di documentazione come Docusaurus eseguono il rendering di un contorno on-page dalle intestazioni senza che tu scriva nulla Quando lavori all'interno di uno di quei sistemi, utilizza la funzione integrata Rimane aggiornato con zero sforzo perché la piattaforma lo rigenera su ogni rendering.
Il generatore guadagna il suo posto ovunque, e & quot; ovunque e quot; è un posto grande GitHub READMEs non auto-generare un blocco di contenuti, quindi una pagina di destinazione del repository ha bisogno di un vero e proprio elenco Markdown impegnato nel file Markdown che viene convertito in qualcos'altro, inviato via email, incollato in un problema, o reso da un visualizzatore minimo ha bisogno di un blocco di contenuti statici perché non c'è un motore per costruirne uno al volo La tabella seguente illustra dove si adatta ogni approccio.
| situazione | Miglior approccio | perché |
|---|---|---|
| GitHub LEGGIMI | Lista statica generata | GitHub esegue il rendering degli ID di intestazione ma non inserisce automaticamente un TOC |
| Wiki o documenti GitLab | [[_TOC_]] gettone |
Nativo, sempre attuale |
| Docusaurus/Pagina MkDocs | Contorno incorporato | Framework lo rende dalle intestazioni |
| File di Markdown semplice per l'esportazione | Lista statica generata | Nessun renderer per costruirne uno al momento della visualizzazione |
| Descrizione della richiesta di emissione o pull | Lista statica generata | Gli ancoraggi funzionano, ma nulla genera automaticamente l'elenco |
La regola pratica: se la cosa che visualizza il tuo Markdown può costruire il contenuto stesso, lascialo Se il tuo Markdown potrebbe essere letto da qualche parte che non può, genera l'elenco e commettilo Quando stai convertendo tra i formati, il Convertitore da markdown a HTML E il Convertitore HTML a Markdown accoppia naturalmente con un blocco di contenuto generato, perché le ancore sopravvivono al viaggio di andata e ritorno.
Come si adatta al resto di un flusso di lavoro Markdown?
Un sommario è un elemento per mantenere leggibili i documenti lunghi e funziona meglio insieme ad alcune abitudini Mantenere stabile il testo dell'intestazione una volta pubblicati i collegamenti ad esso, perché rinominare un'intestazione cambia il suo slug e interrompe ogni collegamento che gli è stato indicato. Quando rinomini, rigenera il contenuto anziché modificare l'unico collegamento che ricordi, poiché una ridenominazione spesso sposta la numerazione dei suffissi duplicati più in basso nel file.
Il contenuto strutturato beneficia di altri strumenti della stessa famiglia Quando un documento si appoggia a dati tabulari, il Generatore di tabelle di Markdown costruisce tabelle pipe correttamente allineate che una tabella digitata a mano non riesce quasi mai a fare nel modo giusto Quando erediti HTML disordinato che deve diventare Markdown pulito, o Markdown pulito che deve diventare HTML, i convertitori gestiscono la traduzione preservando la struttura dell'intestazione E se stai verificando un documento per la lunghezza o il bilanciamento delle parole chiave, il Contatore di parole ti dà i numeri senza incollare la tua bozza in qualcosa basato su cloud.
Tutto viene eseguito nel browser, che conta più di quanto sembri Un README spesso contiene nomi di funzionalità inediti, URL interni o dettagli del client e niente di tutto ciò dovrebbe essere caricato su un server di terze parti solo per creare un elenco di collegamenti Il generatore analizza il tuo Markdown con JavaScript lato client, quindi il documento non lascia mai la tua macchina Se la privacy negli strumenti per sviluppatori è qualcosa a cui pensi, la scrittura su Privacy e strumenti online copre il motivo per cui l'elaborazione locale è l'impostazione predefinita giusta e il Toolkit per sviluppatori web arrotonda il resto delle utenze che raggiungo quotidianamente.
Un esempio veloce
Supponiamo di avere questo documento:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
Impostare l'intervallo da H2 a H3, scegliere un elenco puntato e lasciare i collegamenti di ancoraggio attivi Il generatore produce:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
Il titolo H1 è escluso perché si trova al di sopra dell'intervallo, le sezioni H2 sono a filo a sinistra e i loro figli H3 sono rientrati di un livello Incolla quel blocco appena sotto il titolo nel tuo README e ogni voce salta alla sua sezione su GitHub. Questo è l'intero lavoro, svolto nel tempo necessario per leggere questa frase, e rimane corretto perché una macchina ha calcolato il slugs invece di te.
Domande frequenti
Come funziona un sommario Markdown?
Un indice Markdown è un elenco di collegamenti che puntano agli ancoraggi delle intestazioni all'interno della stessa pagina A ogni intestazione in un documento Markdown viene assegnato un id automatico e un collegamento scritto come Sezione salta su di esso Questo strumento legge le tue intestazioni, costruisce le ancore corrispondenti e assembla l'elenco nidificato per te.
Come vengono generati i collegamenti di ancoraggio?
Gli ancoraggi seguono la regola GitHub slug: il testo dell'intestazione è in minuscolo, la punteggiatura diversa dai trattini viene rimossa e gli spazi diventano trattini. & quot;Imposta & amp; Config" diventa il set-up-config dell'id. Quando due intestazioni producono lo stesso slug, la seconda ottiene un suffisso -1, la terza -2 e così via, corrispondente a come GitHub le esegue.
Funziona con i file GitHub README?
Sì. L'algoritmo slug rispecchia quello che GitHub utilizza per eseguire il rendering degli ID di intestazione, quindi i collegamenti al sommario si risolvono correttamente all'interno di un README su github.com. Incolla il tuo README, scegli i livelli di intestazione e rilascia l'elenco generato sotto il titolo.
Posso scegliere quali livelli di intestazione apparire?
Sì. Impostare un livello minimo e massimo, ad esempio da H2 a H4, e sono incluse solo le intestazioni in tale intervallo La profondità di nidificazione viene misurata rispetto alla direzione inclusa più superficiale, quindi il contorno non inizia mai con una rientranza vuota di grandi dimensioni.
Le intestazioni all'interno dei blocchi di codice sono incluse?
No. Le righe che iniziano con # all'interno di un blocco di codice recintato (delimitato da tripli backtick o tripli tilde) sono trattate come codice, non come intestazioni, quindi frammenti di esempio e commenti di shell non compaiono mai nell'indice.
Qual è la differenza tra un TOC ordinato e non ordinato?
Un sommario non ordinato utilizza marcatori di punto elenco come un trattino per ogni voce, mentre uno ordinato utilizza numeri che incrementano all'interno di ciascun livello di annidamento Scegli ordinato quando i lettori beneficiano di un contorno numerato e non ordinato per un blocco di contenuti più leggero e convenzionale.
Lo strumento supporta le intestazioni Setext?
Sì. legge entrambe le intestazioni ATX che iniziano con le intestazioni # e Setext, dove una riga di testo è sottolineata con segni uguali per H1 o trattini per H2 Entrambi gli stili vengono convertiti in collegamenti di ancoraggio allo stesso modo.
Il generatore Markdown TOC è gratuito e privato?
Sì. è completamente gratuito senza iscrizione e senza limiti Tutto l'analisi avviene nel tuo browser utilizzando JavaScript lato client, quindi il Markdown che incolli non lascia mai il tuo dispositivo e lo strumento continua a funzionare offline una volta caricata la pagina.
