File Transclusion and Hierarchy of Header Levels

Kolen's Avatar


09 Nov, 2015 08:41 AM

Hi, I don't understand how to use file transclusion while having a correct hierarchy of the header levels. What I want to do is that, each individual files are different chapters. And in the main file I want to use file transclusion to combine them into a book.


In the individual files, if I have 3 header levels, and in the main documents when I want to include all of them, I want each files to be under a header of each own.

i.e. Each individual files look like this:

# abc

## def


And in the main files, it becomes

# Chapter 1

## abc

### def


Can it be done?

  1. Support Staff 1 Posted by fletcher on 10 Nov, 2015 01:40 PM

    fletcher's Avatar

    The best example of file transclusion, and many of the tricks you can
    do, is the MultiMarkdown User's Guide:

    The source is on github as well:

    The guide is built using one of several master documents, with chapter
    documents, and separate documents for each section.

    If you use the `make pdf` command on your computer in this directory,
    you can get separate files for each section, each chapter, and a single
    document for the entire guide, each with appropriate header levels.

    Metadata is used to modify header levels correctly based on use.

    Studying the guide is the best way to understand some of the ways to use


  2. 2 Posted by Kolen on 11 Nov, 2015 04:55 AM

    Kolen's Avatar

    Thanks. I downloaded them. One thing I found over there is that the chapter "MultiMarkdown User’s Guide" is the same level and the others like "Introduction". But what I want to do is to have the files transcluded to have titles under the main chapter.

    I played with the header level before, although I used LaTeX Header Level rather than Base Header Level. But it seems it can't do what I want to do.


  3. Support Staff 3 Posted by fletcher on 11 Nov, 2015 01:58 PM

    fletcher's Avatar

    Look again. Many of the files are under their parent files (e.g. the
    Syntax chapter).

    What you want to do is possible. You just have to decide how you want
    things to work, and figure out what header levels to use in the
    individual documents, and what base header level to use in the various

    Also, don't forget that base header level can be negative:

    And in the worst case scenario, simply start by using the actual header
    levels you want everything to have, and no base header levels. That
    gives you absolute control, but no flexibility. It might be an easier
    place to start if you're having trouble though.


  4. 4 Posted by Kolen on 23 Dec, 2015 05:47 AM

    Kolen's Avatar

    I go back and study the MMD User Guide again. And I see how it is done finally: each individual file to be transcluded actually only have 1 single heading 1, all others are of heading 2. So if I am to compile each individual file into a LaTeX and then PDF, each file will only have 1 single chapter.

    What I was thinking is a bit different:

    1. Each individual file are an "article", using LaTeX Header Level 2, there are multiple heading 1 in the file, each corresponds to a chapter.
    2. The Master file (like the are going to be a "memoir", using LaTeX Header Level 1, each files included by {{}} should be under a new heading 1 that wasn't in the original md file, corresponds to different parts in the LaTeX file, and each heading 1 in the individual md file will becomes chapters in the transcluded file, having heading 2. i.e. the transcluded file should have their heading levels shifted.

    With the current file transclusion method like the MMD User Guide used, each individual file has to becomes a "memoir", not article, and each will have a single "part".

    Is mmd_merge providing the functionality I am looking for? Is it deprecated?

    I think using the current tools with file transclusion, I should create the individual files starting with heading level 2, and choose base header level as 1 instead, to provide a proper LaTeX article while transcluded to a proper memoir. Will there be any problems if the md files do not have any heading 1 but start from heading 2? e.g. will MMD Composer render it correctly, including when using the ToC Panel?

  5. Support Staff 5 Posted by fletcher on 23 Dec, 2015 07:22 PM

    fletcher's Avatar

    mmd_merge is a perl script. It's separate from MMD and can be used.

    But the transclusion feature is more powerful I would recommend using that.

    Your files can start with whatever level you like, and Composer will be


  6. Kolen closed this discussion on 02 Mar, 2016 02:51 AM.

Comments are currently closed for this discussion. You can start a new one.

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

Recent Discussions

11 Jan, 2022 02:33 PM
23 Nov, 2021 07:46 PM
10 Jun, 2021 11:53 AM
10 Jun, 2021 01:15 AM
17 Dec, 2020 03:23 PM

Recent Articles