bkuhlmann/tocer

A command line interface for generating Markdown table of contents.

tocer's Issues

Ruby comments in code blocks are included as ToC entries

Expected Behavior

When a document has ruby code blocks that contain comments, the comments should not be included in the table of contents.

The following document is an example of what should happen:

<!-- Tocer[start]: Auto-generated, don't remove. -->

# Table of Contents

- [Introduction](#introduction)
  - [Code Blocks](#code-blocks)

<!-- Tocer[finish]: Auto-generated, don't remove. -->


# Introduction

Text here

## Code Blocks

```ruby
# This is a comment describing the code
class MyRubyClass
end
```

Actual Behavior

The actual behavior is to include ruby comments as table of contents entries:

<!-- Tocer[start]: Auto-generated, don't remove. -->

# Table of Contents

- [Introduction](#introduction)
  - [Code Blocks](#code-blocks)
- [This is a comment describing the code](#this-is-a-comment-describing-the-code)

<!-- Tocer[finish]: Auto-generated, don't remove. -->


# Introduction

Text here

## Code Blocks

```ruby
# This is a comment describing the code
class MyRubyClass
end
```

Steps to Recreate

1. Run tocer -g README.md inside the eebs/tocer_test repo.

Environment

Tocer 3.1.1
Ruby 2.3.1
OSX 10.11.6

Adds blank lines to files with no markdown headers

Overview

We have a markdown file in our wiki with no #header elements:

Design assets like logos and icons can be found on Google Drive.
https://drive.google.com/drive/u/3/folders/xyz

An automated script runs tocer to generate a TOC for all markdown files in the directory. This file currently has 12,150 blank lines preceeding the two lines of content, and 12162 commits in the git log for it.

Screenshots/Screencasts

Steps to Recreate

$ tail Design-Resources.md








Design assets like logos and icons can be found on Google Drive.
https://drive.google.com/drive/u/3/folders/xyz

$ tocer --version
Tocer 12.0.1

$ tocer -b -i Design-Resources.md
  Design-Resources.md

$ git diff | xclip
diff --git a/Design-Resources.md b/Design-Resources.md
index 4491ed77..d8bfcb56 100644
--- a/Design-Resources.md
+++ b/Design-Resources.md
@@ -12148,6 +12148,7 @@
 
 
 
+
 
 
 Design assets like logos and icons can be found on Google Drive.

Desired Behavior

Tocer should not modify files if it did not make any changes.

Environment

$ uname -a
Linux ava.home 5.11.20-200.fc33.x86_64 #1 SMP Wed May 12 12:48:34 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

$ ruby --version
ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-linux]

$ gem --version
3.2.15

$ tocer --version
Tocer 12.0.1

[Documentation] Would it be possible to add an example how to use tocer from within a simple .md file (in the main README)?

Hello Brooke,

I just noticed your tocer-gem on rubygems.org.

I use markdown for my gems and admittedly, I use a very simple markdown.

Other than headers and bold text, and an image here or there, I think that sums up
most of my markdown-use so far in the last ... two years or so. :-)

Anyway, to my suggestion:

• Would it be possible to add a few more, simple examples to tocer, how to use
  it from any existing .md file? E. g. anything that would easily allow me (or other
  people) to jump-start with tocer. Right now I can see the documentation to tocer
  and it's good, -> http://www.rubydoc.info/gems/tocer/7.1.0#command-line-interface-cli

But I am not entirely sure how to use tocer from an existing .md file.

If you could add a minimum example for the next tocer release, that would be
great! Feel free to close this issue at any moment in time.

Thanks!