pub-dev

pub-dev copied to clipboard

Related to #8347

This PR doesn't integrate with anything yet, just provides a new script in the app directory, dart run :toc. The script is heavily borrowed from @ramyak-mehra at https://github.com/dart-lang/pub-dev/issues/3657#issuecomment-826173573

This script generates a fake Pub page (couldn't get all the JS/CSS to load) based on flutter_local_notifications. Running the script generates a app/toc_experiment/index.html you can load in a localhost server. The generated page is the standard README plus a table of contents pinned to the side, with functioning links. This PR is not about the exact format of the page but rather about the parsing logic, all contained within app/bin/toc.dart.

To test, fill the content of app/toc_experiment/readme.md with whatever you like (now it has the notifications package), then:

cd app
dart run :toc
cd toc_experiment
dart pub global activate dhttpd
dhttpd --port 8888

Navigate to http://localhost:8888 in your browser, and there should be a functional table of contents!

---

Here's the new API:

/// A section of the Table of Contents
class TocNode {
  /// What level heading this node is.
  ///
  /// This is not defined by what tag it is using, or how many `#` it has, but rather
  /// how many levels of nesting have occurred in the document so far. That is to say,
  ///
  /// ```md
  /// # Level 1
  /// ### Level 2
  /// ##### Level 3
  /// ```
  int level;

  /// The list of [TocNode] that are nested under this heading.
  List<TocNode> children;

  /// The title of the node, as a string.
  final String title;

  /// The parent heading for this node.
  TocNode? parent;
}

---

• [x] I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.