Add Table of Contents to pages for viewing via github

Aperta
  • Qualcosa non va?
#103 1 commento 1 reazione 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
markdown
Ambito
documentation

Direzione di ricerca

Inizia facendo un inventario delle pagine di documentazione Markdown del repository e rivedendo la discussione esistente della issue su GitPages. Valuta i comandi doctoc proposti e la posizione suggerita dopo l’intestazione di livello 1. Il lavoro è completato quando le pagine pertinenti visualizzate su GitHub hanno sommari navigabili senza includere il titolo della pagina.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary: There's a really easy way to do this, and keep it uptodate - this ticket is to explore whether you would accept a pull-request to implement it...

Motivation

Having seen the Table of Contents links on some docs on github, I've found them to be really useful in getting any overview of the topics covered, and then also for really easy navigation.

Examples are:

I keep coming back to https://github.com/lefticus/cppbestpractices/blob/master/02-Use_the_Tools_Available.md to look for different types of information, and it would save a lot of time and scrolling if users could jump to the section of interest.

Alternatives considered

Searching through the existing issues, I saw #9 which said the solution was to use gitpages,

I downloaded the gitpages PDF, and it doesn't have tables of contents for sections.

And its "Read" feature gives "This site can't be reached" - ERR_CONNECTION_TIMED_OUT - https://lefticus.gitbooks.io/cpp-best-practices/content/

Given how quickly github.com loads Markdown pages, coupled with the convenience of being able to see page histories there and even possibly suggest improvements to the docs, I feel that it's preferable to add Table of Contents to each of the live pages on github.

Possible implementation

For ApprovalTests.cpp, we are using https://github.com/thlorenz/doctoc

It's easy to install:

npm install -g doctoc

Then we run it with this on Windows:

doctoc --title **Contents** .

or this on Unix:

doctoc --title '**Contents**' .

A minor enhancement is to move the generated ToC to after the level-1 heading, so that only level-2 and above headings are included in the ToC.

Consequences

The nice this is that this doesn't require all cppbestpractices contributors to have this tool.

Many edits won't change the ToC, and for those that do, doctoc could be run later by someone who has the tool. (I'd be happy to do that, but it would be better done by someone who has commit-permission on the repo)

Lingua principale
Nessun dato sulla lingua
Stelle
8.9k
Fork
903
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di cpp-best-practices/cppbestpractices

Tutte le issue di cpp-best-practices/cppbestpractices

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.