Skip to content

Commit

Permalink
Switching arrow from U+2191 ↑ to U+21E7 ⇧, regenerate README.md and t…
Browse files Browse the repository at this point in the history 
…esting* files
  • Loading branch information
@Moonbase59
Moonbase59 committed Apr 6, 2024
1 parent 640fe7e commit e28f4bd
Show file tree
Hide file tree
Showing 5 changed files with 145 additions and 144 deletions.
46 changes: 23 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# <a name="gh-toc"></a>gh-toc <a href="#toc" class="goToc">↑</a>
# <a name="gh-toc"></a>gh-toc <a href="#toc" class="goToc">⇧</a>

Quickly create Table-of-Content Markdown for GitHub Markdown files.

![gh-toc-no-border.png](gh-toc-no-border.png)

## <a name="table-of-contents-made-with-gh-toc"></a>Table of Contents _(made with gh-toc)_ <a href="#toc" class="goToc">↑</a>
## <a name="table-of-contents-made-with-gh-toc"></a>Table of Contents _(made with gh-toc)_ <a href="#toc" class="goToc">⇧</a>

<!-- ToC begin -->
<a name="toc"></a>
Expand All @@ -16,8 +16,8 @@ Quickly create Table-of-Content Markdown for GitHub Markdown files.
- [Conversion to HTML, using auto-generated HTML anchors](#conversion-to-html-using-auto-generated-html-anchors)
- [Conversion to HTML, using auto-generated {#…} anchors](#conversion-to-html-using-auto-generated--anchors)
- [More features](#more-features)
- [Generated Markdown using _Anchors: HTML_ and _BL: ↑ToC_](#generated-markdown-using-anchors-html_-and-_bl-toc)
- [Generated Markdown using _Anchors: {#…}_ and _BL: ↑ToC_](#generated-markdown-using-anchors-_-and-_bl-toc)
- [Generated Markdown using _Anchors: HTML_ and _BL: ⇧ToC_](#generated-markdown-using-anchors-html_-and-_bl-toc)
- [Generated Markdown using _Anchors: {#…}_ and _BL: ⇧ToC_](#generated-markdown-using-anchors-_-and-_bl-toc)
- [From simple Table of Contents…](#from-simple-table-of-contents)
- [… to full-fledged Markdown with anchors and backlinks!](#-to-full-fledged-markdown-with-anchors-and-backlinks)
- [Warning if ToC cannot be inserted into full Markdown](#warning-if-toc-cannot-be-inserted-into-full-markdown)
Expand All @@ -27,7 +27,7 @@ Quickly create Table-of-Content Markdown for GitHub Markdown files.
<!-- Generated by gh-toc, https://moonbase59.github.io/gh-toc/ -->
<!-- ToC end -->

## <a name="overview"></a>Overview <a href="#toc" class="goToc">↑</a>
## <a name="overview"></a>Overview <a href="#toc" class="goToc">⇧</a>

> I could never find a _**do-it-all**_, easy to use, online Table-of-Content maker for GitHub (and other) Markdown files. There were many solutions that required downloading or installing something on my computer. For such a trivial task I felt that was unnecessary.
Expand All @@ -52,11 +52,11 @@ Note _gh-toc_ works with ATX-type headings (`###`). It doesn’t try to parse fo

**No other online ToC-Generator I could find handled all the test cases below correctly!**

## <a name="test-file"></a>Test file <a href="#toc" class="goToc">↑</a>
## <a name="test-file"></a>Test file <a href="#toc" class="goToc">⇧</a>

[testing.md](testing.md) is a sample Markdown file with many test cases. Copy its contents into the input box of gh-toc to see what gets generated.

## <a name="conversion-to-html-using-auto-generated-html-anchors"></a>Conversion to HTML, using auto-generated HTML anchors <a href="#toc" class="goToc">↑</a>
## <a name="conversion-to-html-using-auto-generated-html-anchors"></a>Conversion to HTML, using auto-generated HTML anchors <a href="#toc" class="goToc">⇧</a>

This syntax is compatible with almost anything that generates HTML from Markdown, but the HTML is slightly harder to read. You can select if you want `name=` (default) or `id=` HTML anchors generated.

Expand All @@ -77,7 +77,7 @@ in the Markdown file, which Pandoc then converts to this HTML:
- Maximum heading level: 6
- Full MD: ☑
- Anchors: HTML
- BL: ↑ToC (or any other)
- BL: ⇧ToC (or any other)
- Use id: ☐
3. Click `TOC it!` and watch the magic.
4. Copy-paste the contents of the _right_ input box into a text editor and save as `testing-html-anchors.md`.
Expand All @@ -91,7 +91,7 @@ Or watch the generated [`testing-html-anchors.md`](testing-html-anchors.md) _on

**Voilà. Enjoy!**

## <a name="conversion-to-html-using-auto-generated--anchors"></a>Conversion to HTML, using auto-generated {#…} anchors <a href="#toc" class="goToc">↑</a>
## <a name="conversion-to-html-using-auto-generated--anchors"></a>Conversion to HTML, using auto-generated {#…} anchors <a href="#toc" class="goToc">⇧</a>

This syntax is compatible with [_Pandoc_](https://pandoc.org/) and [_PHP Markdown Extra_](https://michelf.ca/projects/php-markdown/extra/), for example.

Expand Down Expand Up @@ -124,35 +124,35 @@ in the Markdown file, which Pandoc then converts to this HTML:

**Voilà again!**

## <a name="more-features"></a>More features <a href="#toc" class="goToc">↑</a>
## <a name="more-features"></a>More features <a href="#toc" class="goToc">⇧</a>

Also try the other options, like auto-generated backlinks to ↑Top or ↑ToC next to each heading! Backlinks use CSS classes `goTop` and `goToc`, so you can even _style_ them!
Also try the other options, like auto-generated backlinks to ⇧Top or ⇧ToC next to each heading! Backlinks use CSS classes `goTop` and `goToc`, so you can even _style_ them!

### <a name="generated-markdown-using-anchors-html_-and-_bl-toc"></a>Generated Markdown using _Anchors: HTML_ and _BL: ↑ToC_ <a href="#toc" class="goToc">↑</a>
### <a name="generated-markdown-using-anchors-html_-and-_bl-toc"></a>Generated Markdown using _Anchors: HTML_ and _BL: ⇧ToC_ <a href="#toc" class="goToc">⇧</a>

```markdown
# <a name="gh-toc"></a>gh-toc <a href="#toc" class="goToc">↑</a>
# <a name="gh-toc"></a>gh-toc <a href="#toc" class="goToc">⇧</a>
```

### <a name="generated-markdown-using-anchors-_-and-_bl-toc"></a>Generated Markdown using _Anchors: {#…}_ and _BL: ↑ToC_ <a href="#toc" class="goToc">↑</a>
### <a name="generated-markdown-using-anchors-_-and-_bl-toc"></a>Generated Markdown using _Anchors: {#…}_ and _BL: ⇧ToC_ <a href="#toc" class="goToc">⇧</a>

```markdown
# gh-toc <a href="#toc" class="goToc">↑</a> {#gh-toc}
# gh-toc <a href="#toc" class="goToc">⇧</a> {#gh-toc}
```

### <a name="from-simple-table-of-contents"></a>From simple Table of Contents… <a href="#toc" class="goToc">↑</a>
### <a name="from-simple-table-of-contents"></a>From simple Table of Contents… <a href="#toc" class="goToc">⇧</a>

![screenshot-simple-toc](screenshot-simple-toc.png)

### <a name="-to-full-fledged-markdown-with-anchors-and-backlinks"></a>… to full-fledged Markdown with anchors and backlinks! <a href="#toc" class="goToc">↑</a>
### <a name="-to-full-fledged-markdown-with-anchors-and-backlinks"></a>… to full-fledged Markdown with anchors and backlinks! <a href="#toc" class="goToc">⇧</a>

![screenshot-fullMD-curly-bl](screenshot-fullMD-curly-bl.png)

### <a name="warning-if-toc-cannot-be-inserted-into-full-markdown"></a>Warning if ToC cannot be inserted into full Markdown <a href="#toc" class="goToc">↑</a>
### <a name="warning-if-toc-cannot-be-inserted-into-full-markdown"></a>Warning if ToC cannot be inserted into full Markdown <a href="#toc" class="goToc">⇧</a>

![screenshot-warning](screenshot-warning.png)

## <a name="the-evolution-of-a-simple-tool"></a>The evolution of a "simple" tool <a href="#toc" class="goToc">↑</a>
## <a name="the-evolution-of-a-simple-tool"></a>The evolution of a "simple" tool <a href="#toc" class="goToc">⇧</a>

It all started out because I looked for a quick way to generate a GitHub README Table-of-Contents. Looking around, most solutions required installing some software my system. No problem so far, but I work on a lot of machines, different operating systems and all. So it would never simply be _available_.

Expand All @@ -172,11 +172,11 @@ Oops, it messed up my long LaTeX _front matter_! Oh, and I’d use that for date

Some people in various forums had hot discussions about whether to use `name` or `id` in HTML anchors. Hmm… **Why not have an option to _switch_ between these?**

Talking _anchors_, **why not include an automatic anchor for the ToC** (because I always forgot to). While we’re at it, think of people wanting to **go to the Top** of the document, too. (Auto-generated when you use _BL: ↑Top_.)
Talking _anchors_, **why not include an automatic anchor for the ToC** (because I always forgot to). While we’re at it, think of people wanting to **go to the Top** of the document, too. (Auto-generated when you use _BL: ⇧Top_.)

**Not everything is GitHub.** So let’s _use_ the GitHub anchors and find a way to include anchors _on the actual headings_ when _not_ using GitHub (which does it automatically when previewing Markdown files). It actually took a while, and lots of reading and testing, to find a way that would work "everywhere", from GitHub to Pandoc-generated HTML, because Markdown doesn’t support it natively. Fortunately it _does_ support using HTML code, so the most compatible way could be found. **_Anchor_ was created.** You can switch between no anchors, HTML, and the curly bracket notation.

Now what **frustrates** me and others most when reading my ultralong READMEs? Right! **Not being able to jump back to the Table of Contents!** We’re creating anchors anyway, so **why not add a backlink feature?** Now this should work with minimal or no effort, and both on GitHub and files that are later post-processed into HTML. It should be **unobtrusive**, like the little up-arrow many web pages show nowadays to go to `↑Top`. Oh, and **stylable using CSS**. And hey, why not let me choose between **↑Top** and **↑Toc** jumping? What I eventually liked best was **a little stylable up-arrow at the right end of each heading**, technically _inside_ the heading. And of course the **_BL_** (backlink) selection.
Now what **frustrates** me and others most when reading my ultralong READMEs? Right! **Not being able to jump back to the Table of Contents!** We’re creating anchors anyway, so **why not add a backlink feature?** Now this should work with minimal or no effort, and both on GitHub and files that are later post-processed into HTML. It should be **unobtrusive**, like the little up-arrow many web pages show nowadays to go to `⇧Top`. Oh, and **stylable using CSS**. And hey, why not let me choose between **⇧Top** and **⇧Toc** jumping? What I eventually liked best was **a little stylable up-arrow at the right end of each heading**, technically _inside_ the heading. And of course the **_BL_** (backlink) selection.

I’m _so_ happy that I can copy-paste my README into _gh-toc_ now, select options, and out comes a readily-usable, linked and backlinked file, you wouldn’t believe it!

Expand All @@ -187,13 +187,13 @@ Now I’m _really_ happy. Until I find the next feature, that is…
> **And _now_ you know the rest of the story! (So far.)**

## <a name="known-problems"></a>Known problems <a href="#toc" class="goToc">↑</a>
## <a name="known-problems"></a>Known problems <a href="#toc" class="goToc">⇧</a>

- ~~_gh-toc_ will "brute-force replace" all text between the ToC start marker `<!-- ToC begin -->` and the end marker `<!-- ToC end -->` with the new Table of Contents, _even if they are in a code block_. Avoid that for now, or don’t use the _Full MD_ option in this case and insert the ToC manually.~~
_Now fixed and ToC inserting/replacing is safe, even if the "ToC begin/end" comments are out of sequence or one is missing. An alert will pop up if none are found and the ToC cannot be inserted in FullMD mode._

- Selecting _FullMD_ + _Anchor: \{\#…\}_ will overwrite other than anchor definitions within the curly braces, i.e. `{#anchor .red}` → `{#new-anchor}`. Selecting _Anchor: –_ (None) doesn’t modify existing curly brace definitions.

## <a name="the-real-magic"></a>The Real Magic <a href="#toc" class="goToc">↑</a>
## <a name="the-real-magic"></a>The Real Magic <a href="#toc" class="goToc">⇧</a>

https://moonbase59.github.io/gh-toc/
5 changes: 3 additions & 2 deletions gh-toc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ function tocIt(inputMD, minHeading, maxHeading, fullMD, addAnchors, addBL, useID
// addBL (backlink) can be: "none", "toc", "top"

// These backlinks can be added to headings; the "blank" is U+2002, an &ensp;
var goToc = ' <a href="#toc" class="goToc">↑</a>';
var goTop = ' <a href="#top" class="goTop">↑</a>';
// Arrows: U+21E7 ⇧, U+2191 ↑, U+1F51D+U+FE0E 🔝︎
var goToc = ' <a href="#toc" class="goToc">⇧</a>';
var goTop = ' <a href="#top" class="goTop">⇧</a>';
var firstMDLine = -1; // no first real MD line found yet

var anchorAttribute = "name";
Expand Down
6 changes: 3 additions & 3 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,12 +132,12 @@ <h2>The Real Magic</h2>

&ensp;

<label for="addBL" title="Generate backlinks? (—=no, ↑ToC=Table of Contents, or ↑Top=Top of document)">BL:</label>
<label for="addBL" title="Generate backlinks? (—=no, ⇧ToC=Table of Contents, or ⇧Top=Top of document)">BL:</label>

<select id="addBL">
<option value="none" selected>—</option>
<option value="toc">↑ ToC</option>
<option value="top">↑ Top</option>
<option value="toc">⇧ ToC</option>
<option value="top">⇧ Top</option>
</select>

&ensp;
Expand Down
Loading

0 comments on commit e28f4bd

Please sign in to comment.