[2.x] Blade-based table of contents generator

[emmadesilva]

Abstract

This allows the table of contents to be customized by publishing the Blade component, and is now styled using real TailwindCSS.

It's also up to 20 times faster, and up to 40 times faster not factoring in the Blade timings.

• Fixes [2.x] Refactor HydeFront styles to TailwindCSS #2024 (comment)

Changes

If you have used the Hyde\Framework\Actions\GeneratesTableOfContents class in custom code, you will likely need to update that code for the rewritten class.

If you have called the getTableOfContents method of the DocumentationPage class in custom code, you will need to update that usage as the that message has been removed.

If you have published the resources/views/components/docs/sidebar-item.blade.php component, you will need to update it to call the new component instead of the old generator rendering.

• Adds a new resources/views/components/docs/table-of-contents.blade.php component containing the structure and styles for the table of contents
• Rewrites the GeneratesTableOfContents class to use a custom implementation instead of using CommonMark
• The execute method of the GeneratesTableOfContents class now returns an array of data, instead of a string of HTML. This data should be fed into the new component
• Removed the table-of-contents.css file as styles are now made using Tailwind

---

Benchmarks

Before Benchmarks

Small Document Benchmark

$markdown = "# Level 1\n## Level 2\n## Level 2B\n### Level 3\n";

• First run: ~10ms
• Subsequent runs: Average of 10,000 iterations at 0.373ms

Hyde Documentation Benchmarks

• Hyde pages (hyde-pages.md): 4.068ms average of 1,000 runs
• Hyde kernel (hydekernel.md): 4.369ms average of 1,000 runs

Scaling Test

When appending the hydekernel document to itself three times, the benchmark shows:

• 12.447ms average of 1,000 runs
• Scales linearly with document size

New System

Small Document Benchmark

$markdown = "# Level 1\n## Level 2\n## Level 2B\n### Level 3\n";

• First run: ~2.056ms
• After warmup:
  • Second run: 0.249ms
  • Average of 10,000 runs: 0.128ms

Hyde Documentation Benchmarks

• Hydekernel docs (×1): 0.269ms average of 1,000 runs
• Hydekernel docs (×3): 0.655ms average of 1,000 runs
  • Scales slightly less than linearly
  • (×5 reaches 1.083ms)

Generation Without Blade

Lightweight Generation Benchmark

$markdown = "# Level 1\n## Level 2\n## Level 2B\n### Level 3\n";

• First run: ~1.7ms
• After warmup:
  • Second run: 0.020ms
  • Average of 10,000 runs: 0.009ms

Scaling Performance

Hydekernel docs benchmark:

• ×1: 0.128ms average of 1,000 runs
• ×3: 0.369ms average of 1,000 runs
• ×5: 0.621ms average of 1,000 runs
• ×10: 1.278ms average of 1,000 runs

This shows a very close to linear scaling performance.

Comparison

Based on the benchmarks, let's compare the performance of the new system to the old one:

1. For the small document:

   • Old system: 0.373ms (average of 10,000 runs after warmup)
   • New system: 0.128ms (average of 10,000 runs after warmup)
   • Speedup: ~2.91x faster

2. For the hydekernel.md document:

   • Old system: 4.369ms (average of 1,000 runs)
   • New system: 0.269ms (average of 1,000 runs)
   • Speedup: ~16.24x faster

3. For the hydekernel.md document x3:

   • Old system: 12.447ms (average of 1,000 runs)
   • New system: 0.655ms (average of 1,000 runs)
   • Speedup: ~19x faster

In summary:

• For small documents, the new system is about 2.9 times faster.
• For larger documents (like hydekernel.md), the new system is about 16 times faster.
• For even larger documents (hydekernel.md x3), the new system is about 19 times faster.

The new system not only shows significant speed improvements but also scales better with larger documents. While the old system scaled linearly with document size, the new system shows sub-linear scaling, which is a substantial improvement in performance, especially for larger documents.
ed improvements but also scales better with larger documents. While the old system scaled linearly with document size, the new system shows sub-linear scaling, which is a substantial improvement in performance, especially for larger documents.

Comparison (Just Generation Without Blade)

Based on the benchmarks, let's compare the performance of the new system (just generation without Blade) to the old system:

1. For the small document:

   • Old system: 0.373ms (average of 10,000 runs after warmup)
   • New system: 0.009ms (average of 10,000 runs after warmup)
   • Speedup: ~41.44x faster

2. For the hydekernel.md document:

   • Old system: 4.369ms (average of 1,000 runs)
   • New system: 0.128ms (average of 1,000 runs)
   • Speedup: ~34.13x faster

3. For the hydekernel.md document x3:

   • Old system: 12.447ms (average of 1,000 runs)
   • New system: 0.369ms (average of 1,000 runs)
   • Speedup: ~33.73x faster

4. For the hydekernel.md document x5:

   • Old system: (Not provided, but can be estimated to be around 20.745ms based on linear scaling)
   • New system: 0.621ms (average of 1,000 runs)
   • Estimated speedup: ~33.41x faster

In summary:

• For small documents, the new system is about 41 times faster.
• For larger documents (like hydekernel.md), the new system is about 34 times faster.
• For even larger documents (hydekernel.md x3 and x5), the new system maintains a speedup of about 33-34 times faster.

The new system shows dramatic speed improvements across all document sizes. It also demonstrates excellent scaling characteristics, maintaining its performance advantage even as document size increases. This represents a substantial improvement in performance, especially for larger documents, and should significantly enhance the overall efficiency of the markdown processing pipeline.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (f93a7ba) to head (ccd2942).
Report is 45 commits behind head on new-asset-system.

Additional details and impacted files

@@                 Coverage Diff                  @@
##             new-asset-system     #2045   +/-   ##
====================================================
  Coverage              100.00%   100.00%           
- Complexity               1906      1914    +8     
====================================================
  Files                     195       195           
  Lines                    5080      5094   +14     
====================================================
+ Hits                     5080      5094   +14     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[emmadesilva]

Remaining tasks:

Undefined array key "slug" with this:

## test
### test

Add this PR to release notes