mistermicheels/markdown-notes-tree

Generate Markdown trees that act as a table of contents for a folder structure with Markdown notes

markdown-notes-tree's Issues

Add description in README files to the tree

This tool is exactly what I was going to write but you saved my day 🚀

However I have a feature request I'd like to discuss with you. I want to add a short paragraph of text below the folder title in a folder's README in order to place it in the parent (up until root) folder's tree as a description to the folder.

The idea behind this is to provide a detailed overview to new developers to one of our repositories with a large and complex folder structure.

Example:

A README.md in a subfolder of a folder:

---

subfolder

this is a short description

• subsubfolder

---

generating the following tree for the parent folder

---

parent folder name

• subfolder - this is a short description
  • subsubfolder

---

or for longer paragraphs

---

parent folder name

• subfolder
  this is a short description
  • subsubfolder

---

I would be willing to prove a PR if you consider this to be a viable feature. What do you think?

Unable to parse markdown with header images

Hello! 👋

Looking over the README, it looks like the following is an issue when users have HTML image headers in their markdown.

The first non-empty line of a note (potentially after YAML front matter) is a level 1 heading with the note's title

Example use case

$ npx markdown-notes-tree **/*.md
Processing files in order to build notes tree
Error: No title found for Markdown file /path/to/docs-as-code/playbooks/general/incident-severity-scale.md


$ head -4 general/incident-severity-scale.md
<img width="100" src="../../assets/images/sammy-heart.png" alt="Sammy Love"
align="right">

# Incident Severity Scale

It would be awesome if there was actual markdown parsing to allow for image headers.

add configuration for number of spaces?

I use a standard indent of 2 spaces for my markdown files; the automatic 4-space indent of markdown-notes-tree breaks my linting and prettier hooks. Would it be possible to add a configuration option to set number of spaces?

fails catastrophically if a title is not found

some of my markdown is generated by jsdoc2md and that can fail and create an empty file.

Regardless of the reason for the empty file it causes mardown-notes-tree to bail.
Error: No title found for Markdown file ...

It would be nice if:

• it didn't fail on these cases (>= skip behaviour would be acceptable)
• there was a way to have a default title that would be applied

ideas:

• perhaps the filename could be used?
• or maybe an entry for the file gets created but no link is generated?

for now i'll try to stop the empty file from being created but i still see this failing behaviour as too heavy a hammer

Enh: auto link the "up" directory

it would be nice if one could automatically nav from the current directories README.md up a level. i.e. equivalent of [up](../README.md)

However, no rush as the auto breadcrumbs nav that a lot of markdown situations come with is fine for us.

similar feature would be a [top](../../README.md) entry

(p.s. promise that is my last issue lol)

add pre-commit hook?

I think it would be very useful to use this as a pre-commit hook. I think all that is required is to add a .pre-commit-hook.yaml file to the repo

-   id: markdown-notes-tree
    name: markdown-notes-tree
    description: '`markdown-notes-tree` will generate Markdown trees that act as a table of contents for the folder structure.'
    entry: markdown-notes-tree
    language: node

bitbucket defaults to Home.md

Bitbucket defaults to Home.md -- rather than a bitbucket specific option could there be an flag for the file name?