2 Questions: Referencing md in different directory; multiple summary.md?

[stratus-ss]

Thanks a lot for the project I am enjoying it!

I had a couple of questions. I have some documentation shows how do something via the cli and the same thing via the UI. Because of this there are some common md files. I was trying to construct a summary.md like this:

- [Introduction](../Intro.md)
    - [Prerequisites](../Quay_Prerequisites.md)
    - [Quay CLI Install](Quay_CLI_Install.md)
        - [Quay Config: init-config-bundle-secret](../InitConfigBundle.md)
        - [Quay Config: Create QuayRegistry](Quay_CLI_Objects.md)
        - [OPTIONAL: Quay Mirror](Quay_CLI_Mirror.md)
        - [OPTIONAL: Quay ProxyCache](Quay_CLI_ProxyCache.md)

However, this causes the following error

src/VMWare/Quay/CLI/summary.md:1:3:stat ../Intro.md: invalid argument
src/VMWare/Quay/CLI/summary.md:2:7:stat ../Quay_Prerequisites.md: invalid argument
src/VMWare/Quay/CLI/summary.md:4:11:stat ../InitConfigBundle.md: invalid argument

I also tried using the abs path but that didn't work either. I believe the code is here

stitchmd/main.go

Lines 214 to 217 in 9b8f7f5

	if err != nil {
	log.Println(err)
	return errors.New("error reading markdown")
	}

Question 2:

Can you make a summary file that references and renders another summary file? I may want to render both the UI and CLI bits together. I understand that I could just put them together myself but I was thinking something like this:

- [Introduction](../Intro.md)
    - [Prerequisites](../Quay_Prerequisites.md)
    - [Quay CLI Install](Quay_CLI_Install.md)
        - [Quay Config: init-config-bundle-secret](../InitConfigBundle.md)
        - [Quay Config: Create QuayRegistry](Quay_CLI_Objects.md)
        - [OPTIONAL: Quay Mirror](Quay_CLI_Mirror.md)
        - [OPTIONAL: Quay ProxyCache](Quay_CLI_ProxyCache.md)
    - [Quay UI Install](../UI/summary.md)   

Thanks!

[abhinav]

Hey there! Thanks for the issue.

Question 1: The choice to prevent references outside the current directory was partly a security measure. I don't want the program to try to grab, say, ~/.aws/config. There are two workarounds to this:

1. Create symlink to ../Intro.md and ../Quay_Prerequisites.md in the current directory.

   ln -s ../Intro.md ./Intro.md
   ln -s ../Quay_Prerequisites.md.md ./Quay_Prerequisites.md
   

   That explicitly brings them in-scope in the current directory and you should be able to use them.

2. Place the summary.md in the parent directory -- this will require adjusting the other links though, so this is probably a bad idea for you.

I would be open to adding an -unsafe flag to allow referencing files above the current directory. Would that work for you? (edit: Adding in #112.)

Question 2: This isn't possible today, but totally planned. I've been tracking it in #4, although the issue description is different because I wasn't completely sure about the UX. I've left a comment with something closer to what you're describing above. I may poke at it if I have time in the near future.

EDIT(2023-11-07): Both pieces of functionality are now available in v0.8.0.

[stratus-ss]

thanks for the response. I had setup the symlink prior to posting, I was just wondering if there was a native solution

regarding your answer to question2, i'd be willing to get my hands dirty if you have some time to show me where some of this code lives and what your current thoughts around it are

[abhinav]

I was just wondering if there was a native solution

There is now. Not yet released, but I've added an --unsafe flag.

I'd be willing to get my hands dirty if you have some time to show me where some of this code lives and what your current thoughts around it are

That sounds great!
The fuzziest bit here was deciding what UX I wanted. Your use case was useful in coming up with something here. I'm thinking that to "include" another summary file from a summary file, you have to do this:

![foo](bar.md)

This is technically an image tag in Markdown, but the summary file doesn't support images, so we can use that. (I'd be open to using a different symbol, but '!' feels right.)
If you include another summary file like this, it'll get nested under that item.

Some of the bits are:

• stitch contains logic for parsing a summary file. It converts a Markdown AST into a more simplified layout. It currently defines two kinds of items: links and text. It'll have to learn about embeds.
• Following that, information flows into collector which takes the parsed summary file and builds up a tree of markdown files and links. This is probably where we'll want to recursively run another collection to expand an embedded summary file.

At a high level, the information flow is:

flowchart TB
  SummaryFile{{Summary file}} --> stitch.ParseSummary -->|Simplified representation| Summary{{Summary}}
  MD1{{Markdown file}} & MD2{{Markdown file}} & Summary --> Collector -->|Load all Markdown ASTs, build a tree| Collection{{Collection}}
  Collection --> Transformer -->|Adjust levels, rewrite links, etc.| Transformed{{Collection}}
  Transformed --> Generator --> Markdown{{Markdown}}

Loading

Feel free to poke around! No pressure or commitment. I'll be happy to answer questions.
And I'll still look into this when I have time in the near future if you end up not doing it.

[abhinav]

@stratus-ss The inclusion functionality as discussed and the --unsafe flag are both available in v0.8.0.

[stratus-ss]

Thanks for following up on this!