Multi-File Documents in different folders

Randy Walker's Avatar

Randy Walker

10 Oct, 2018 06:46 PM

I have a folder full of markdown files that get used by a different tool. I'd like to keep a Marked-compatible Multi-File document outside of that folder so the other tool doesn't see it. I can't seem to get this to work. I've tried mmd-merge with the directory path but images don't get rendered. Am I missing something? Is this capability not supported by Marked?

  1. 1 Posted by Randy Walker on 10 Oct, 2018 08:10 PM

    Randy Walker's Avatar

    I forgot, I tried mmd_merge because I wanted the indented header levels. Is that possible without the #merge syntax multi-file document?

  2. Support Staff 2 Posted by Brett on 10 Oct, 2018 08:38 PM

    Brett's Avatar

    If the paths to the images within the included files are relative paths,
    they have to be relative to the main index file. Thus, if your file were
    in "base" and your documents were in "base/files" and your images were
    in "base/images":

    |- files/
    |- images/image1.jpg

    The image reference in files/ (when included in would
    need to be ![](images/image1.jpg), even though if that file were viewed
    directly, it would need to be ![](../images/image1.jpg).

    When Marked merges all of the files, it's not rendering the Markdown
    until the merge is complete, for fairly obvious reasons (footnotes, for
    example, defined in a separate file, would never render, table of
    contents can't be generated until the document structure is complete,
    etc.). Thus, once it's all combined, the index file's location is the
    only reference point on disk for any relative image referenced in an
    included file. Everything acts as if it was referenced from the location
    of the index file. Does that make sense?

    Also, mmd_merge is the only format that allows a structure/hierarchy to
    be specified, thus the only one that modifies header levels of included


  3. 3 Posted by Randy Walker on 10 Oct, 2018 08:42 PM

    Randy Walker's Avatar

    My images, are in a subfolder of files like files/images/image1.jpg

    Does this make a difference?

  4. Support Staff 4 Posted by Brett on 10 Oct, 2018 08:50 PM

    Brett's Avatar

    It might be easiest if you drew out (or zipped up a sample) the
    structure, showing where the index file is in relation to the included
    files and the images.

    Based on that example, and assuming the index is in the same folder as
    the "files" folder, the images would need to be referenced as
    ![](files/images/image1.jpg), whereas I'm assuming they currently just
    reference ![](images/image1.jpg).

    Is there a specific reason you need to keep the Marked index document
    outside of the folder with the files? Putting it in the same folder
    would alleviate the need to have different paths, and as it is, it
    sounds like altering your paths would break images in whatever other app
    you're using with the same files.


  5. 5 Posted by Randy Walker on 10 Oct, 2018 09:04 PM

    Randy Walker's Avatar

    I've attached a screenshot of what a sample project folder would look like.

    I'd like to keep the Marked index file outside of the folder with all of the component documents for ease of use with the other tool that uses my markdown files. Right now, it's just one file but I imagine use cases where I'll have different index files including different subsets of the component files

    currently referencing the images as ![](images/image1.jpg) yes

  6. Support Staff 6 Posted by Brett on 10 Oct, 2018 11:54 PM

    Brett's Avatar

    Would it make a difference to your other tool if the index had an extension other than md? I usually name mine index.marked (any extension will work).

    - Brett

  7. 7 Posted by Randy Walker on 11 Oct, 2018 12:57 AM

    Randy Walker's Avatar

    Oooh, good call. The other tool only supports a few extensions so I could try this!

  8. Support Staff 8 Posted by Brett on 16 Oct, 2018 08:28 PM

    Brett's Avatar

    I don't know why I didn't think to mention this, but you could try setting an "include base" metadata key to specify the base directory your other files are in.

    Add this at the top of the document (modified for your actual path names)

    Include Base: /Users/youruser/Documents/project/files

    That should alter the base directory that Marked is looking for included files from, so when an image is referenced with "images/image1.jpg", it should look for it in "files/images/image1.jpg". I can't guarantee this works, it's a bit fickle and I haven't tested in this case, but worth a shot if you're still figuring this out.

Reply to this discussion

Internal reply

Formatting help / Preview (switch to plain text) No formatting (switch to Markdown)

Attaching KB article:


Attached Files

You can attach files up to 10MB

If you don't have an account yet, we need to confirm you're human and not a machine trying to post spam.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac