Skip to content

Latest commit

 

History

History
60 lines (39 loc) · 3.1 KB

CONTRIBUTING.md

File metadata and controls

60 lines (39 loc) · 3.1 KB
Raw

Contributing

Thanks for taking an interest in contributing to this Jekyll TOC snippet. 🎉

Creating an Issue

jekyll-toc makes a lot of assumptions about the HTML it's given. Just like parsing HTML with regex is a bad idea, so is parsing HTML as simple strings. So I expect that there'll be issues along the way.

  • If you'd like to report an issue with the TOC that was generated by this snippet, follow the appropriate "Bug Report" issues template; it'll make the process of hunting the down bugs much easier if I have the information from the template.
    • I don't want to close/ignore your issue if I don't have enough information to reproduce your issue.
  • If you have a feature request, use the "Feature Request" issue template and provide the necessary details.
    • Keep in mind that because I'm not using an actual XML parser, some requests may just not be possible to achieve.

Creating a PR

Got a new feature you'd like to add or a bug fix? Be awesome and submit a PR! A few things to keep in mind:

  • This snippet is designed to be light-weight and simple. If you add a new feature that's a costly operation, I'll likely ask that you split off the toc.html in a separate toc-feature.html so the main project can remain light-weight.
    • I don't mean create a separate repo, just another file in _includes. This would allow users to 'opt-in' to the performance hit.
  • Parsing HTML as strings is insane, so make sure that your changes are robust enough to withstand most syntactically correct HTML.
  • Add unit tests to test whichever feature you are adding or bug you are fixing. If the bug has an existing issue, link to the issue in the Front Matter as a comment.

Unit Tests

This project has unit tests to ensure consistent TOC generation and reliability so existing features don't break. This means existing unit tests should never be changed in order to make your code pass the tests.

Unit tests are located in the _test directory; each file represents a single test. This directory is a Jekyll collection which outputs files, which are run through a Python 3.8 script checking that the actual values are what is expected.

Creating Your Own Test

As mentioned, each file is a single test which has actual values and expected values. Take a look at existing tests but they should follow this template.

---
---

{% capture markdown %}
# Heading 1
{% endcapture %}
{% assign text = markdown | markdownify %}

{% include toc.html html=text %}

<!-- /// -->

<ul>
    <li><a href="#heading-1">Heading 1</a></li>
</ul>

The <!-- /// --> is the directive used to tell our Python script where the actual value stops and where the expected value starts. The markdown that you are testing should go inside the {% capture %} tags which is then converted to markdown and modify the {% include %} statement with whatever parameters your test requires.

Running Tests

Build the Jekyll site which processes all of our tests along with our current TOC snippet and then run the Python 3 script.

bundle exec jekyll build
python plutils/pltest.py