Home → Questions →

File Transclusion and Hierarchy of Header Levels

• Edit

Kolen

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.

e.g.

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

   

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

   http://fletcher.github.io/MultiMarkdown-4/

   The source is on github as well:

   https://github.com/fletcher/MultiMarkdown-4/tree/gh-pages

   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
   transclusion.

   F-

   • Edit

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

   

   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.

   Thanks.

   • Edit

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

   

   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
   metadata.

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

   http://fletcher.github.io/MultiMarkdown-4/metadata.html#baseheaderlevel

   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.

   F-

   • Edit

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

   

   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 MMD_Users_Guide.md) are going to be a "memoir", using LaTeX Header Level 1, each files included by {{....md}} 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?

   • Edit

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

   

   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
   fine.

   F-

   • Edit

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