Skip to content

Conversation

Copilot
Copy link

@Copilot Copilot AI commented Aug 24, 2025

This PR implements an automated Table of Contents (TOC) generation system that allows maintaining the mdBook SUMMARY.md file from a simpler toc.md format.

Problem

Previously, the book-src/SUMMARY.md file had to be manually maintained using mdBook's verbose format with specific indentation and linking patterns. This made TOC updates error-prone and time-consuming.

Solution

Created a simplified toc.md format and automated generation system:

Simple toc.md format:

## File System
- Read file line by line | 01-01-read-file-line-by-line.md
- Mmap file | 01-02-mmap-file.md
- Check file existence | 01-04-file-exists.md

## Cryptography  
- Calculate SHA-256 digest of a file | 02-01-sha-digest.md

Automatically generates mdBook's SUMMARY.md:

- [File System]()

  - [Read file line by line](./01-01-read-file-line-by-line.md)
  - [Mmap file](./01-02-mmap-file.md)
  - [Check file existence](./01-04-file-exists.md)

- [Cryptography]()

  - [Calculate SHA-256 digest of a file](./02-01-sha-digest.md)

Features

  • Simplified Format: Clean, readable toc.md with section headers and pipe-separated items
  • Exact Compatibility: Generated SUMMARY.md is byte-for-byte identical to the original
  • Build Integration: Automatically runs during make serve, CI builds, and npm scripts
  • Special Case Handling: Correctly handles Database section links, Text Processing formatting, and file path prefixes

Usage

# Manual generation
node generate-summary.js
make generate-summary
npm run generate-summary

# Automatic generation during:
make serve           # local development  
# CI/CD builds        # GitHub Actions

The toc.md file becomes the source of truth, while SUMMARY.md is auto-generated and should not be manually edited.

Fixes #107.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copy link
Author

Copilot AI commented Aug 24, 2025

@jiacai2050 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

@Copilot Copilot AI changed the title [WIP] toc 的内容最好可以从一个 toc.md 里面解析出来 Implement automated TOC generation from toc.md file Aug 24, 2025
Copilot finished work on behalf of jiacai2050 August 24, 2025 09:24
@Copilot Copilot AI requested a review from jiacai2050 August 24, 2025 09:24
@jiacai2050 jiacai2050 closed this Aug 26, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

toc 的内容最好可以从一个 toc.md 里面解析出来
2 participants