Add Table of Contents to pages for viewing via github

Abierto
  • ¿Algo no está bien?
#103 1 comentario 1 reacción 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
35/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
markdown
Área
documentation

Línea de trabajo

Empieza por inventariar las páginas de documentación Markdown del repositorio y revisar la discusión existente de la issue sobre GitPages. Evalúa los comandos doctoc propuestos y la ubicación sugerida después del encabezado de nivel 1. Se considera terminado cuando las páginas relevantes vistas en GitHub tienen tablas de contenido navegables sin incluir el título de la página.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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)

Lenguaje dominante
Sin datos de lenguaje
Estrellas
8.9k
Forks
903
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de cpp-best-practices/cppbestpractices

Todos los issues de cpp-best-practices/cppbestpractices

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.