Support a way to visualize folder structures

[damithc]

In technical documentations, often we need to describe a folder structure, to explain where to put certain files for example.

It is nice if we can provide a syntax that MarkBind can convert to a nice visual. More generally, it can even be used to explain other types of tree-like structures.

PlantUML doesn't seem to support folder visualizations. https://jaredforsyth.com/treed/ seem to doing something along these lines but not sure if it can fit MarkBind.

[riyadh-h]

Hello there!

It is nice if we can provide a syntax that MarkBind can convert to a nice visual.

I agree, but I'm also not sure if the interactive features Treed provides are necessary (e.g., folder collapsing, keyboard navigation/shortcuts, etc.). Perhaps we can try implementing the folder visualization tool without them?

[damithc]

I agree, but I'm also not sure if the interactive features Treed provides are necessary (e.g., folder collapsing, keyboard navigation/shortcuts, etc.). Perhaps we can try implementing the folder visualization tool without them?

Yes, I don't think we need the instructiveness. If there is a suitable third-partly library that we can plug in easily, it's fine to have such extra features. But if we are going to roll our own implementation, we can definitely go for a simple static visualization.

[tlylt]

I find this interesting and would like to work on it if possible :) The main reference of the intended outcome is tree.nathanfriend.io

Proposed syntax:

<tree>
Edit me to generate
  a
    nice
      tree
        diagram!
        :)
</tree>
<tree>
- Edit me to generate
  - a
    - nice
    - tree
        - diagram!
        - :)
</tree>

To

Edit me to generate
└── a
    └── nice
        └── tree
            ├── diagram!
            └── :)

(example taken from the reference site)

Some available configurations (any combinations of the 3 boolean attributes):

<tree trailingSlash></tree>
<tree root></tree>
<tree fullPath></tree>

[damithc]

@tlylt Yes, this one seems like a reasonable solution.

[damithc]

Some available configurations (any combinations of the 3 boolean attributes):

<tree trailingSlash></tree>
<tree root></tree>
<tree fullPath></tree>

Feels like the trailing slash should be determined from the text itself. i.e., give a slash if there is a slash given in the source; no slash otherwise (even for intermediate nodes) The other two settings too feel like specific to folder trees whereas we can make this feature work for any tree-like structure, not just folder trees. What do you think?

[tlylt]

Feels like the trailing slash should be determined from the text itself. i.e., give a slash if there is a slash given in the source; no slash otherwise (even for intermediate nodes)

Yup, that is reasonable. The ability to add a trailing slash is more of a convenient option and not strictly necessary.

The other two settings too feel like specific to folder trees whereas we can make this feature work for any tree-like structure, not just folder trees. What do you think?

I agree. It does limit the scope of what this feature can do.

I am not too sure if we should generalize this use case to other tree-like structures though. Would a plantuml mindmap work well for those cases?

I am leaning towards the idea of "tree" for folder structures, as a parallel to the tree UNIX command for displaying nested folders and files in the console.

[damithc]

I am not too sure if we should generalize this use case to other tree-like structures though. Would a plantuml mindmap work well for those cases?

Both PlantUML mindmap and work breakdown structure diagrams are viable alternatives but neither has the left-aligned visualization we usually use for folder trees. So, this feature still has value and I expect it to be light-weight than PlantUML (e.g., no need to have Java installed)

Most likely this feature will be used for visualizing folder structures but we don't have to tie it down to folders only if we can help it. That way, it can be used for other folder-like visualizations when needed.

On a related note, as the output will be text (not a png/svg) we can consider allowing more rich content e.g., tooltips, images, icons etc. in nodes. Does that make sense?

[tlylt]

Most likely this feature will be used for visualizing folder structures but we don't have to tie it down to folders only if we can help it. That way, it can be used for other folder-like visualizations when needed.

Yup sounds good. Wonder if there is any advice on how to still keep it user-friendly for the specific purpose of folder structure visualization? Although customizations like trailing slash and add-root may be irrelevant for other tree-like structures, I feel that eliminating them limits the usefulness of this feature. Or is this a necessary/unavoidable price to pay to make a component more general?

On a related note, as the output will be text (not a png/svg) we can consider allowing more rich content e.g., tooltips, images, icons etc. in nodes. Does that make sense?

I think for a start we could do with simple text outputs. Adding on to that would be allowing inline markdown, something similar to what other components support. Afterward, if we do go into more complicated functionalities such as folder collapsing/keyboard shortcuts, then it might need more HTML/CSS/JS.

[damithc]

Wonder if there is any advice on how to still keep it user-friendly for the specific purpose of folder structure visualization? Although customizations like trailing slash and add-root may be irrelevant for other tree-like structures, I feel that eliminating them limits the usefulness of this feature. Or is this a necessary/unavoidable price to pay to make a component more general?

You are right. If those customizations come for free, OK to use. But otherwise, we can skip them, as they don't actually add much value - certainly not worth implementing ourselves. e.g., root and trailing slash can be easily added in the node text itself, and I can't imagine a situation for using full path in every node. But I could be wrong.

[tlylt]

For discussion:

Font

Going with text output, the font choice affects how the symbols are rendered on screen. Following the approach from the reference site mentioned earlier, I am thinking of using font-family: "Fira Code", "Fira Mono", monospace; So if 'Fira Code' is not available, it looks like this(i.e. monospace):

If 'Fira Code' is available:

Should we import the fira code font to ensure that it is always available (I think this is not the case for all users) or ok with the rendering sequence of Fira (if present) -> monospace ?

---

Further styling

Inline markdown support can be done for the tree nodes:

• Fira (because of the change in font size, the 'gap' when using this font is a little bit more obvious)
• Monospace

Note that not all markdown/components work.

• text styles, icons, images seem to work fine, with the caveat of a possible increment of the height of the tree node
• tooltip, thumbnail, and some other block-level elements are behaving weirdly/not working

Will this level of support be enough?

---

Syntax

Currently, the syntax to support will be (every two spaces a level)

<tree>
Edit me to generate
  a
    nice
      tree
        diagram!
        :)
</tree>

Wonder if we should also support the use of a list? (chopping off the - for the user if they specify it)

<tree>
- Edit me to generate
  - a
    - nice
      - tree
        - diagram!
        - :)
</tree>

[damithc]

nice work @tlylt

Will this level of support be enough?

Yes, definitely good enough for a first release. How about things like ==abcd== and abcd{.text-danger}?

No preference on font.

Yes, we can support list syntax as I feel it is visually more comforting/intuitive than the bare indentation syntax (?). OK to not support it too.

[tlylt]

How about things like ==abcd== and abcd{.text-danger}?

Yes, almost all text styles specified here are working, with the exception of "center align" because it doesn't work well within a paragraph of text.

abcd{.text-danger}

This is a bit tricky (as far as I know). The markdown-it-attrs plugin that we use to support this way of adding classes/attributes typically applies to markdown syntax.

• abcd{.text-danger} kind of works and it is converted into <p class="text-danger">abcd</p>, which is a block level element.
• abcd{.text-danger} efg doesn't works and it is converted into <p>abcd{.text-danger} efg</p>
• I think it works by appending the attributes to a target HTML element, which is created based on the markdown syntax parsing(not part of the markdown-it-attrs). If it is just part of pure text, then there is no element for it to append the attributes to.

For the tree feature, because it's supporting only "inline markdown" (and inline HTML)

• if the tree node content is already wrapped in markdown syntax, it works just fine.
  • e.g !!Underline!!{.text-danger} => <span class="underline text-danger">Underline with {text=danger}</span>.
• However, if the tree node content is pure text. it doesn't work
  • the workaround is to specify the content as an inline HTML element
  • e.g <span class="text-danger">Underline</span>

I think it is possible to support it, but there's a bit of ambiguity (should the attribute applies to just abcd or │ ├── abcd) and implementation complexity. Will the workaround be sufficient?

Screenshot:

<tree>
C:/course/
  textbook/
    `index.md`
  **index.md**
    ~~index.md~~
    %%dimmed%%
    Super^script^
    ****Super Bold****
    !!Underline!!
    !!Underline with {text=danger}!!{.text-danger}
    <span class="text-danger">!!Underline!!</span>
    ->Center-align<-
  __reading.md__
  ++site.json++
  ==hello==
</tree>

Output:

[damithc]

I think it is possible to support it, but there's a bit of ambiguity (should the attribute applies to just abcd or │ ├── abcd) and implementation complexity. Will the workaround be sufficient?

Yes @tlylt , I think it's sufficient.