ToC ou barre latérale dans GitHub Wiki

87

Comment créer une ToC ou un menu de la barre latérale dans un wiki GitHub?

J'en ai vu quelques mentions et gollum le backend semble le supporter, mais comment le faire dans un projet GitHub actuel?

Il devrait mieux être basé sur les en-têtes que j'ai dans la page automatiquement.

Ces liens le mentionnent tous, mais ne montrent pas comment le faire:

  • https://gist.github.com/379469 - un piratage JavaScript
  • https://github.com/blog/774-git-powered-wikis-improved - GitHub le mentionnant:

    «Les wikis GitHub ont une capacité peu documentée pour les pieds de page et les barres latérales, ce que certains de nos auteurs de Wiki basés sur git connaissent bien. Le nouvel éditeur de Wiki vous donne une édition limitée basée sur le Web des pieds de page et des barres latérales que vous avez sur votre site. "

wolle
la source
3
J'ai développé GitHub Wikifier: un Git Hook pré-commit qui générera toute la table des matières dont vous aurez besoin. Écrivez simplement votre contenu et laissez-le prendre le dessus. Cela peut valoir un chèque. github.com/kuroir/GitHub-Wikifier
MarioRicalde
Sur Isaacs: github.com/isaacs/github/issues/504
Ciro Santilli 郝海东 冠状 病 六四 事件 法轮功
Le code de @MarioRicalde a été
Jonny

Réponses:

76

Pendant que votre solution fonctionne, il existe un moyen plus simple de le faire à l'aide de l'interface Web de GitHub. Vous pouvez simplement créer une page nommée _Sidebaret / ou _Footer.

Voir les instructions détaillées dans le générateur de menu de la barre latérale Github Wiki avec plusieurs niveaux .

Modifier L'article original a disparu et je ne le trouve pas dans le cache, j'ai donc mis à jour le lien.

Nicérobot
la source
7
@CodeSherpa ils sont accessibles à https://github.com/[user]/[repo]/wiki/_Sidebar/_editethttps://github.com/[user]/[repo]/wiki/_Footer/_edit
nicerobot
1
L'article était génial mais donne des informations incorrectes (ou obsolètes) sur la façon d'obtenir l'URL du wiki. Dans le cas où vous êtes aussi perdu que moi, vous devez utiliser l'URL https://github.com/<username>/<projectname>.wiki.gitou SSH [email protected]:<username>/<projectname>.wiki.git.
NightOwl888
1
Ces instructions détaillées sont assez pauvres. Qu'est-ce qu'un [[link]]? Mettre une URL là-dedans entraîne l'affichage de l'URL entière.
Pithikos
3
@Pithikos c'est Github Markdown parler. Les instructions ne sont pas là pour vous apprendre Markdown. Ils sont là pour expliquer les barres latérales.
nicerobot
2
@nicerobot et la meilleure façon d'expliquer quelque chose est d'utiliser un exemple concret ..
Pithikos
26

Lorsque vous êtes dans le wiki de votre projet, il y a un lien Ajouter une barre latérale personnalisée . Cliquez dessus.

Entrez la description de l'image ici

Vous avez maintenant une page que vous modifiez comme vous le feriez pour n'importe quelle autre page Markdown . Pour créer une table des matières, vous devez le faire manuellement. Il n'y a pas de méthode automatisée (en août 2014). Donc par exemple:

# My menu
* [Home][home]
* [Technical documentation][techdocs]
* [User manual][usermanual]

[home]: https://github.com/myproject/wiki/Home
[techdocs]: https://github.com/myproject/wiki/Technical-documentation
[usermanual]: https://github.com/myproject/wiki/User-manual
Pithikos
la source
25

D'accord. Voyons si je comprends bien:

  1. Clonez votre wiki GitHub. (Il y a une section Git dans le wiki. Vous pouvez récupérer votre code de type wiki.)
  2. Créer _Sidebar.md
  3. Dans les pages wiki normales, utilisez [[link]]pour la barre latérale
  4. Validez et repoussez vers GitHub

Ce processus est une douleur dans le cul. Je suis surpris que ce wiki «gollum» soit accepté.

Aussi: _Sidebar.md est donc global pour toutes les pages . Je devrais organiser mon wiki dans des dossiers, afin que je puisse définir différentes barres latérales pour différentes pages.

wolle
la source
2
Selon la documentation, vous pouvez ajouter différentes barres latérales pour différents dossiers: "Les barres latérales affectent toutes les pages de leur répertoire et tous les sous-répertoires qui n'ont pas de fichier de barre latérale propre." voir: github.com/github/gollum
Subfuzion
10

Notez que la question d'origine portait sur la création d'une barre latérale (facile, résolue dans les réponses) ou d'une table des matières réelle (sans réponse).

Une chose que je peux dire, c'est que la syntaxe du wiki gollum 2.1 autorise une [[_TOC_]]balise, mais un wiki GitHub ne le reconnaîtra pas (encore?).

marque
la source
4
Avez-vous eu de la chance? C'est terriblement frustrant d'être venu de Trac où toutes ces choses étaient faciles à faire.
jooks
Je pense qu'une meilleure réponse à la question originale sur la façon de créer une table des matières "basée sur les en-têtes que j'ai dans la page automatiquement" est que c'est actuellement impossible avec GitHub Wiki.
avernet
Il s'agit actuellement d'un problème ouvert (trop paresseux pour rechercher le nombre) sur lequel des centaines de personnes ont commenté. Aucun mot de retour de GitHub pour le moment :(
abalter
Les principaux problèmes GitHub qui font référence à cela à partir du 19/01/2017 sont les suivants: 1. Markdown - Table des matières 2. Insérer une table des matières automatiquement générée TOC sur les fichiers de démarque rendus comme README.md
ckib16
4

Je pense que cela est décrit dans le GollumREADME . (Voir les sections d'en-tête et de la barre latérale.)

Essentiellement, vous créez un _footer.extet _sidebar.extdans le répertoire contenant le contenu de la page.

Seandavi
la source
2

J'ai implémenté le module npm github-wiki-sidebar pour aider les utilisateurs de github à créer et maintenir facilement le menu de la barre latérale.

Source et résultat: https://raw.githubusercontent.com/wiki/adriantanasa/github-wiki-sidebar/images/github-wiki-sidebar-generator.png

Pages source (telles qu'affichées dans l'administration du wiki):

Home
Installation
Roadmap
Usage
Usage: Command line modifiers
Usage: Init Mode

Résultat (avec commande personnalisée):

Pré-requis:

  • clonez localement votre dépôt wiki github (affiché en bas à droite de l'interface utilisateur du wiki)
  • installer la barre latérale github-wiki

    git clone <https://github.com/<username>/<my-project-name>.wiki.git
    npm install -g github-wiki-sidebar
    

Créez / mettez à jour votre menu wiki:

  • créer de nouvelles pages / renommer des pages sur votre administrateur wiki github.com
  • exécutez localement le script github-wiki-sidebar dans votre dossier de référentiel wiki

    cd /path/to/<my-project-name>.wiki
    # this fetches latest changes, generates sidebar file (_Sidebar.md) and pushes changes to github
    github-wiki-sidebar --git-push
    

Le module permet la personnalisation de la sortie de démarque, y compris l'ordre des éléments, le séparateur de catégorie, le modèle pour le menu, le format des liens et autres.

adtanasa
la source
0

GitHub générera automatiquement une table des matières du document:

  1. Faites en sorte que le document de type AsciiDoc au lieu de Markdown.
  2. Insérez :toc:au début du document.
Dogweather
la source