TOC tự động trong đánh dấu hương vị github

Có thể tạo Mục lục tự động bằng cách sử dụng Github Flavored Markdown không?

Tôi đã tạo hai tùy chọn để tạo mã thông báo cho github có hương vị:

Công cụ dòng lệnh DocToc ( nguồn ) yêu cầu node.js

npm install doctoc

npx doctoc . để thêm mục lục vào tất cả các tệp markdown trong thư mục hiện tại và tất cả các thư mục con.

Ứng dụng web của DocToc

Nếu bạn muốn dùng thử trực tuyến trước, hãy truy cập trang doctoc , dán liên kết của trang đánh dấu và nó sẽ tạo ra một bảng nội dung mà bạn có thể chèn ở đầu tệp đánh dấu của bạn.

Github Wikis và Neo

Như Matthew Flaschen đã chỉ ra trong các bình luận bên dưới, đối với các trang wiki của nó, GitHub trước đây đã không tạo ra các neo doctocphụ thuộc vào.

CẬP NHẬT: Tuy nhiên, họ đã khắc phục vấn đề này .

Trang GitHub (về cơ bản là trình bao bọc cho Jekyll) dường như sử dụng kramdown , thực hiện tất cả Maruku , và do đó có hỗ trợ cho mục lục được tạo tự động thông qua một tocthuộc tính:

* auto-gen TOC:
{:toc}

Dòng đầu tiên chỉ bắt đầu một danh sách không có thứ tự và thực sự bị ném đi.

Điều này dẫn đến một tập hợp các danh sách không có thứ tự lồng nhau, sử dụng các tiêu đề trong tài liệu.

Lưu ý: điều này sẽ hoạt động cho các trang GitHub, không phải GitHub Flavored Markdown (GFM) như được sử dụng trong các bình luận hoặc trang wiki. AFAIK một giải pháp không tồn tại cho điều đó.

Nếu bạn chỉnh sửa các tệp Markdown bằng Vim, bạn có thể thử plugin vim-markdown-toc này .

Cách sử dụng rất đơn giản, chỉ cần di chuyển con trỏ đến nơi bạn muốn nối Mục lục và chạy :GenTocGFM, đã xong!

Ảnh chụp màn hình:

Đặc trưng:

1. Tạo mã thông báo cho các tệp Markdown. (Hỗ trợ GitHub Hương vị Markdown và Redcarpet)

2. Cập nhật mã thông báo hiện có.

3. Tự động cập nhật toc khi lưu.

Nó không tự động, nhưng nó sử dụng các biểu thức chính quy của Notepad ++:

Thay thế tất cả đầu tiên bằng thứ hai (loại bỏ tất cả các dòng không có tiêu đề)

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

Sau đó (chuyển đổi tiêu đề III thành dấu cách)

-##
        -

Sau đó (chuyển đổi tiêu đề II thành dấu cách)

-#
    -

Sau đó (xóa các ký tự không sử dụng ở đầu và cuối tiêu đề liên kết)

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

Sau đó (chuyển đổi mã thông báo cuối cùng chữ thường và dấu gạch ngang thay vì dấu cách)

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

Loại bỏ bảng cuối cùng không sử dụng và dấu gạch ngang ban đầu:

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

Xóa ký tự vô dụng trong các liên kết:

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

Và cuối cùng thêm dấu ngoặc quanh các liên kết cuối cùng:

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

Và Voila! Bạn thậm chí có thể đặt điều này trong một macro toàn cầu nếu bạn lặp lại nó đủ thời gian.

Điều đó là không thể, ngoại trừ các cách giải quyết được đề xuất.

Tôi đã đề xuất tiện ích mở rộng Kramdown TOC và các khả năng khác cho support@github.com và Steven! Ragnarök trả lời với thông thường:

Cảm ơn các đề xuất và liên kết. Tôi sẽ thêm nó vào danh sách yêu cầu tính năng nội bộ của chúng tôi để nhóm xem.

Hãy nêu câu hỏi này cho đến khi nó xảy ra.

Một cách giải quyết khác là sử dụng Asciidoc thay vì Markdown, kết xuất TOC . Tôi đã chuyển sang cách tiếp cận này cho nội dung của tôi ngày nay.

Github Flavored Markdown sử dụng RedCarpet làm công cụ Markdown của họ. Từ repo RedCarpet :

: with_toc_data - thêm các neo HTML vào từng tiêu đề trong HTML đầu ra, để cho phép liên kết với từng phần.

Có vẻ như bạn cần phải đạt được ở cấp độ kết xuất để đặt cờ này, điều này không thể thực hiện được trên Github. Tuy nhiên, bản cập nhật mới nhất cho Github Pages, có vẻ như tính năng neo tự động được bật cho các tiêu đề, tạo các tiêu đề có thể liên kết. Không chính xác những gì bạn muốn, nhưng nó có thể giúp bạn tạo TOC cho tài liệu của bạn dễ dàng hơn một chút (mặc dù theo cách thủ công).

Một cách rất thuận tiện để đạt được mục lục cho tệp mardown khi làm việc với Visual Studio Code là phần mở rộng Markdown-TOC .

Nó có thể thêm mã thông báo vào các tệp đánh dấu hiện có và thậm chí giữ cho mã thông báo cập nhật.

Có thể tạo trang web tự động với http://documentup.com/ từ README.mdtệp. Nó không tạo ra một TOC, nhưng đối với nhiều người nó có thể giải quyết lý do muốn tạo một TOC.

Một lựa chọn khác cho Documentup là Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown là một bộ tiền xử lý markdown cho Github.

Sử dụng Gitdown bạn có thể:

• Tạo mục lục
• Tìm URL chết và Định danh phân đoạn
• Bao gồm các biến
• Bao gồm các tập tin
• Lấy kích thước tập tin
• Tạo huy hiệu
• Ngày in
• In thông tin về chính kho lưu trữ

Gitdown hợp lý hóa các tác vụ phổ biến liên quan đến việc duy trì trang tài liệu cho kho lưu trữ GitHub.

Sử dụng nó rất đơn giản:

var Gitdown = require('gitdown');

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

Bạn có thể có nó dưới dạng một tập lệnh riêng biệt hoặc có nó như là một phần của thói quen tập lệnh xây dựng (chẳng hạn như Gulp ).

Sử dụng coryfklein / doctoc , một nhánh của thlorenz / doctoc không thêm " được tạo bằng DocToc " vào mỗi mục lục.

npm install -g coryfklein/doctoc

Đồng nghiệp của tôi @schmiedc và tôi đã tạo một tập lệnh GreasMonkey cài đặt một TOCnút mới bên trái của h1nút sử dụng markdown-jsthư viện tuyệt vời để thêm / làm mới mục lục.

Ưu điểm so với các giải pháp như doctoc là nó tích hợp vào trình soạn thảo wiki của GitHub và không cần người dùng làm việc trên dòng lệnh của họ (và yêu cầu người dùng cài đặt các công cụ như node.js). Trong Chrome, nó hoạt động bằng cách kéo thả vào trang Tiện ích mở rộng, trong Firefox, bạn sẽ cần cài đặt tiện ích mở rộng GreasMonkey.

Nó sẽ hoạt động với đánh dấu đơn giản (nghĩa là nó không xử lý các khối mã chính xác, vì đó là phần mở rộng GitHub để đánh dấu). Đóng góp chào mừng.

Đây không phải là một câu trả lời trực tiếp cho câu hỏi này vì rất nhiều người đã cung cấp cách giải quyết. Tôi không nghĩ việc tạo TOC đã được Github hỗ trợ chính thức cho đến nay. Nếu bạn muốn GitHub tự động hiển thị Mục lục trên các trang xem trước GFM của họ, vui lòng tham gia thảo luận về vấn đề yêu cầu tính năng chính thức .

Hiện tại không thể sử dụng cú pháp đánh dấu (xem phần thảo luận đang diễn ra tại GitHub ), tuy nhiên bạn có thể sử dụng một số công cụ bên ngoài như:

• Trình tạo nội dung trực tuyến ( raychenon / play-table-content )
• arthurhammer / github-toc - tiện ích mở rộng trình duyệt thêm mục lục vào repos GitHub

Thay AsciiDocvào đó sử dụng thay thế (ví dụ README.adoc), ví dụ

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

## A

### A2

## B

### B2

như đề xuất trong bình luận này . Kiểm tra bản demo tại đây .

Đối với Github's Texteditor Atom, hãy kiểm tra plugin tuyệt vời này (hoặc "gói" trong Atom-lingo), tạo ra "TOC (mục lục) của các tiêu đề từ các tệp đánh dấu được phân tích cú pháp" :

đánh dấu

Sau khi được cài đặt dưới dạng gói Atom, bạn có thể sử dụng phím tắt ctrl-alt-cđể chèn TOC dựa trên cấu trúc đánh dấu tài liệu của bạn ở vị trí con trỏ hiện tại ...

Ảnh chụp màn hình:

Bàn phím nguyên tử

markdown-toc cung cấp cho bạn các ràng buộc khóa mặc định sau để kiểm soát plugin trong Atom:

• ctrl-alt-c => tạo TOC tại vị trí con trỏ
• ctrl-alt-u => cập nhật TOC
• ctrl-alt-r => xóa TOC

Các tính năng bổ trợ (từ README của dự án)

• Tự động liên kết thông qua các thẻ neo, ví dụ # A 1→#a-1
• Kiểm soát độ sâu [1-6] với depthFrom:1vàdepthTo:6
• Bật hoặc tắt liên kết với withLinks:1
• Làm mới danh sách lưu với updateOnSave:1
• Sử dụng danh sách theo thứ tự (1. ..., 2. ...) với orderedList:0

Đây là một kịch bản shell tôi đã ném cùng nhau ngày hôm nay cho điều này. Có thể cần phải điều chỉnh nó cho nhu cầu của bạn, nhưng nó nên là một điểm khởi đầu tốt.

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/^#//'

Nếu bất cứ ai biết một cách tốt hơn để thực hiện những thay thế # cuối cùng đó, vui lòng thêm một nhận xét. Tôi đã thử nhiều thứ và không hài lòng với bất kỳ thứ gì, vì vậy tôi chỉ bắt bẻ nó.

Hiện tại đã có một hành động GitHub hoàn thành việc này:

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

1. Chỉ định vị trí của TOC (tùy chọn), vd README.md

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

2. Thiết lập quy trình công việc, vd .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

Phần lớn các câu trả lời khác yêu cầu cài đặt một số công cụ. Tôi tìm thấy một giải pháp trực tuyến nhanh chóng và dễ dàng https://imthenachoman.github.io/nGitHubTOC .

Đối với bất kỳ đầu vào đánh dấu, nó tạo ra bảng đầu ra nội dung. Bạn có thể chỉ định mức tiêu đề tối thiểu và tối đa.

Mã nguồn được đặt tại https://github.com/imthenachoman/nGitHubTOC