Github aromalı işaretlemede otomatik TOK

Github Aromalı Markdown kullanarak otomatik İçindekiler oluşturmak mümkün müdür ?

Github aromalı işaretleme için bir toc oluşturmak için iki seçenek oluşturdum:

DocToc Komut Satırı Aracı ( kaynak ) node.js gerektirir

npm install doctoc

npx doctoc . geçerli ve tüm alt dizinlerdeki tüm işaretleme dosyalarına içindekiler tablosu eklemek için.

DocToc WebApp

Önce çevrimiçi denemek istiyorsanız, doctoc sitesine gidin, işaretleme sayfasının bağlantısını yapıştırın ve etiketleme dosyanızın üstüne ekleyebileceğiniz bir içerik tablosu oluşturur.

Github Wikileri ve Çapaları

Matthew Flaschen'nin aşağıdaki yorumlarda belirttiği gibi, wiki sayfaları için GitHub daha önce doctocbağlı olan çapaları üretmemişti .

GÜNCELLEME: Ancak bu sorunu çözdüler .

GitHub Sayfaları (temel olarak Jekyll için bir sarıcıdır) , tüm Maruku'yu uygulayan ve bu nedenle otomatik olarak oluşturulan bir içindekiler tablosuna destek veren kramdown kullanıyor gibi görünüyor bir tocözellik aracılığıyla :

* auto-gen TOC:
{:toc}

İlk satır sırasız bir liste başlatır ve aslında atılır.

Bu, belgedeki üstbilgileri kullanarak iç içe dizisiz listeler kümesiyle sonuçlanır.

Not: Bu, yorumlarda veya wiki sayfalarında kullanılan GitHub Aromalı İşaretleme (GFM) için değil, GitHub Sayfaları için çalışmalıdır. AFAIK bunun için bir çözüm mevcut değil.

Markdown dosyalarını Vim ile düzenlerseniz, bu vim-markdown-toc eklentisini deneyebilirsiniz .

Kullanımı basit, sadece imlecinizi eklemek istediğiniz yere taşıyın İçindekiler ve çalıştırın :GenTocGFM, bitti!

Ekran görüntüleri:

Özellikleri:

1. Markdown dosyaları için toc oluşturun. (GitHub Aromalı Markdown ve Redcarpet'i destekleyin)

2. Mevcut toc'yi güncelleyin.

3. Kaydetme sırasında otomatik güncelleme toc.

Otomatik değildir, ancak Notepad ++ normal ifadelerini kullanır:

Tümünü önce ikincisiyle değiştir (başlık içermeyen tüm satırları kaldırır)

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

Sonra (III. Başlıkları boşluklara dönüştürür)

-##
        -

Ardından (II. Başlıkları boşluklara dönüştürür)

-#
    -

Ardından (bağlantı başlığının başında ve sonunda kullanılmayan karakterleri kaldırın)

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

Ardından (boşluk yerine son jetonları küçük harfe ve tireye dönüştür)

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

Kullanılmayan son kiloları ve ilk kısa çizgileri kaldırın:

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

Bağlantılardaki yararsız karakterleri kaldırın:

(\].*?)(?:\(|\))
\1

Ve son bağlantılara parantez ekleyin:

\](?!\()(.*?)$
\]\(\1\)

Ve voilà! Yeterince zaman tekrarlarsanız bunu global bir makroya bile koyabilirsiniz.

Önerilen geçici çözümler dışında bu mümkün değildir.

Ben önerdi support@github.com ve Kramdown TOK uzantısı ve diğer olasılıkları Steven! Ragnarök şöyle cevap verdi:

Öneri ve bağlantılar için teşekkürler. Ekibin görmesi için dahili özellik istek listemize ekleyeceğim.

Bu soruyu gerçekleşene kadar oylayalım.

Başka bir geçici çözüm Markdown kullanımı Asciidoc, etmektir Tocs hale yapar . Bugünlerde içeriğim için bu yaklaşıma geçtim.

Github Aromalı Markdown, Markdown motoru olarak RedCarpet kullanıyor. Gönderen redcarpet repo :

: with_toc_data - her bölüme bağlanmaya izin vermek için çıkış HTML'sindeki her başlığa HTML bağlantılarını ekleyin.

Görünüşe göre Github'da mümkün olmayan bu bayrağı ayarlamak için oluşturucu seviyesine gitmeniz gerekiyor. Bununla birlikte, Github Pages'daki en son güncelleme , başlıklar için otomatik sabitlemenin açık olduğu ve bağlanabilir başlıklar oluşturduğu görülüyor. Tam olarak ne istediğinizi değil, ancak belgeniz için bir TOC oluşturmanıza yardımcı olabilir (elle de olsa).

Visual Studio Code ile çalışırken mardown dosyası için bir içindekiler tablosu elde etmenin çok uygun bir yolu Markdown-TOC uzantısıdır .

Mevcut işaretleme dosyalarına bir toc ekleyebilir ve hatta kaydetme sırasında toc'u güncel tutabilir.

Otomatik olarak bir web sayfasını oluşturmak mümkündür http://documentup.com/ gelen README.mddosyaya. Bir İçindekiler oluşturmak değil, ama çoğu için bir İçindekiler oluşturmak istemenin nedenini çözebilir.

Documentup'a başka bir alternatif Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown , Github için bir işaretleme ön işlemcisidir .

Gitdown'u kullanarak şunları yapabilirsiniz:

• İçindekiler Oluştur
• Ölü URL'leri ve Parça Tanımlayıcılarını bulma
• Değişkenleri dahil et
• Dosyaları dahil et
• Dosya boyutunu al
• Rozet Oluştur
• Basım tarihi
• Depo hakkındaki bilgileri yazdırın

Gitdown, GitHub deposu için bir belge sayfası tutmayla ilgili ortak görevleri kolaylaştırır.

Kullanımı basittir:

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

Ayrı bir komut dosyası olarak ya da derleme komut dosyası yordamının ( Gulp gibi ) bir parçası olarak kullanabilirsiniz.

Her içindekiler tablosuna " DocToc ile oluşturulmuş " ifadesi eklemeyen thlorenz / doctoc çatalı coryfklein / doctoc kullanın .

npm install -g coryfklein/doctoc

Meslektaşım @schmiedc ve ben içindekiler tablosu eklemek / yenilemek için mükemmel kütüphaneyi kullanan düğmenin soluna yeni bir düğme yükleyen bir GreaseMonkey betiği oluşturduk .TOCh1markdown-js

Doctoc gibi çözümlere göre avantajı GitHub'ın wiki düzenleyicisine entegre olması ve kullanıcıların komut satırlarında çalışmalarına gerek duymaması (ve kullanıcıların aşağıdaki gibi araçları yüklemelerini gerektirmesidir) node.js ). Chrome'da, Uzantılar sayfasına sürükleyip bırakarak çalışır, Firefox'ta GreaseMonkey uzantısını yüklemeniz gerekir.

Düz işaretleme ile çalışır (yani, işaretleme için bir GitHub uzantısı olduğu için kod bloklarını doğru işlemez). Katkıları bekliyoruz.

Birçok insan geçici çözüm sağladığından, bu soruya doğrudan bir cevap değildir. Bir TOK oluşturmanın bugüne kadar henüz Github tarafından resmi olarak desteklendiğini düşünmüyorum. GitHub'ın GFM önizleme sayfalarında bir İçindekiler Tablosu oluşturmasını istiyorsanız, lütfen resmi özellik isteği sorunu hakkındaki tartışmaya katılın .

Şu anda markdown sözdizimini kullanmak mümkün değildir ( GitHub'da devam eden tartışmaya bakın ), ancak aşağıdaki gibi bazı harici araçları kullanabilirsiniz:

• Çevrimiçi İçerik Oluşturucu Tablosu ( raychenon / içindekiler tablosu )
• arthurhammer / github-toc - GitHub depolarına bir içindekiler tablosu ekleyen tarayıcı uzantısı

Alternatif olarak AsciiDocbunun yerine (örneğin README.adoc), örn.

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

Bu yorumda önerildiği gibi . Demoyu buradan kontrol edin .

İçin Github en Texteditor Atom üretir bu müthiş eklenti (veya "paket" Atom-lingo), kontrol "çözümlü markdown gelen başlıklarının TOK (İçindekiler tablosunu)" dosyaları:

markdown-toc

Atom-paketi olarak kurulduktan sonra ctrl-alt-c, mevcut imleç konumundaki markdown-doc yapınıza dayalı bir TOC eklemek için kısayolu kullanabilirsiniz ...

Ekran görüntüleri:

Atom Keybindings

markdown-toc, Eklentiyi Atom'da kontrol etmek için aşağıdaki varsayılan anahtar bağlantılarını verir:

• ctrl-alt-c => imleç konumunda TOC oluştur
• ctrl-alt-u => TOC'yi güncelle
• ctrl-alt-r => TOC'yi sil

Eklenti Özellikleri (projenin README'sinden)

• Bağlantı etiketleri aracılığıyla otomatik bağlantı, örn. # A 1→#a-1
• Derinlik kontrol [1-6] depthFrom:1vedepthTo:6
• İle bağlantıları etkinleştirme veya devre dışı bırakma withLinks:1
• İle kaydetme sırasında listeyi yenile updateOnSave:1
• Sipariş listesini (1. ..., 2. ...) ile birlikte kullanın orderedList:0

İşte bugün bunun için birlikte attığım bir kabuk senaryosu. İhtiyaçlarınız için ayarlamanız gerekebilir, ancak iyi bir başlangıç ​​noktası olmalıdır.

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

Herkes bu son # değiştirmeleri yapmanın daha iyi bir yolunu biliyorsa, lütfen bir yorum ekleyin. Ben çeşitli şeyler denedim ve hiçbiri ile mutlu değildi, bu yüzden sadece kaba zorladı.

Şimdi bunu yapan bir GitHub Eylemi var:

https://github.com/marketplace/actions/toc-generator

1. İçindekiler (konum) konumunu belirtin örn. README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. Kurulum iş akışı örn. .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

Diğer cevapların çoğunluğu bazı araçların yüklenmesini gerektirir. Hızlı ve kolay bir çevrimiçi çözüm buldum https://imthenachoman.github.io/nGitHubTOC .

Herhangi bir işaretleme girişi için içerik çıktısı tablosu oluşturur. Minimum ve maksimum başlık seviyesini belirleyebilirsiniz.

Kaynak kodu https://github.com/imthenachoman/nGitHubTOC adresinde bulunur.