Add Table of Contents to pages for viewing via github

Offen
  • Stimmt etwas nicht?
#103 1 Kommentar 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Anfängerfreundlichkeit
35/100
Issue-Typ
Dokumentation
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
markdown
Bereich
documentation

Rechercherichtung

Beginne damit, die Markdown-Dokumentationsseiten des Repositorys zu inventarisieren und die bestehende Issue-Diskussion über GitPages zu prüfen. Bewerte die vorgeschlagenen doctoc-Befehle und die vorgeschlagene Platzierung nach der level-1-Überschrift. Erledigt bedeutet, dass die relevanten auf GitHub angezeigten Seiten navigierbare Inhaltsverzeichnisse enthalten, ohne den Seitentitel einzuschließen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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)

Vorherrschende Sprache
Keine Sprachdaten
Sterne
8.9k
Forks
903
Keine gemergten PRs in 30 T.

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus cpp-best-practices/cppbestpractices

Alle Issues in cpp-best-practices/cppbestpractices

Ähnliche Issues

Weitere Issues zu Documentation

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.