Ability to have nested file structure

[dblessing]

We need the ability to retain our repository's nested markdown file structure. Users may either read documentation in our repository or on the doc site. Links and images will not work properly in this case with slate at the moment. Even if I am able to get slate to automatically render nested markdown files the links are still not going to work.

Do you have any tips/suggestions for this problem or would you be willing to support this in slate? Please let me know if you need further explanation of the issue.

[lord]

Not quite sure what you mean — what is a nested markdown file?

[dblessing]

Hi @lord Instead of having everything compiled into a single documentation page can Slate be altered to support multiple pages?

[lord]

You can currently have multiple pages if you create multiple .md files, but there's no way to link between them in the nav sidebar, which is why I was curious what you mean by "nested".

[kubino]

Maybe he didn't know 'includes:' directive. I did came he because of the 'nested' keyword :) I would like to have structured(nested) format, as I find it more maintainable and also gives me better visual experience when adding/changing methods (think about lot of json examples) .

I am thinking about structure like this:

index.md
includes:
-foo

and then in the in the includes file structure like this

/includes
/includes/foo.md
includes/foo/about.md
includes/foo/list.md
includes/foo/update.md
includes/foo/get.md
....

foo.md would have another 'includes:' directive
includes:
-about
-list
-update
-get

What do you think? Would it be possible somehow? Thanks a lot for any comment

[lord]

Ah, like nested includes inside another include. You should be able to manually include things with middleman's partial syntax, which is how includes work under-the-hood.

[janicecmt]

I want to be able to nest includes too. I tried the partial syntax referenced above and it rendered as is within the file. It looks like that's primarily for folks writing directly in HTML or inside Ruby code. Is there a solution that works from within Markdown files?

[lord]

Rendered as-is? Did you change your file type to .md.erb?

[janicecmt]

The partial files I'm referencing using that syntax are using .md.erb extensions. I did not alter the file name of the top-level include file listed from the index.html.md file where the references to the partials live.

To see if location or file name was the problem, I've tried using a separate directory with relative paths and using the include directory with and without a leading _ for the file names.

This is the reference to the partials inside an _foo.md file in my includes:

<%= partial "../partials/partial1" %>
<%= partial "../partials/partial2" %>
<%= partial "partial3" %>
<%= partial "partial4" %>

Inside the source/partials directory I have the following files:

partial1.md.erb
_partial2.md.erb

Inside the source/includes directory I have the following files:

_foo.md
partial3.md.erb
_partial4.md.erb

See the attached screenshot to see it rendered in my local Middleman instance:

ETA: I also just tried and got the same results with "includes/partialK" for files with and without the _ inside the includes directory in case the path needs to be from the source directory.

[janicecmt]

Hmmm, it looks like in the rendered output the quotes around the file names are curly quotes but I have straight quotes in my source file.

[lord]

Is your index file called index.md.erb?

[janicecmt]

No. I didn't rename the file from the sample/getting started project so it's index.html.md and the top level includes are foo.md as indicated above. I only used .md.erb for the partial files.

[lord]

Ah, try that! Renaming the index.

[janicecmt]

It didn't help :(

[lord]

I don't have time to look now since I'm preparing for a new term of school to start, but I'm reopening this so I can take a look later.

[Nevario]

Hi Everyone,

Just wondering if there was ever a working solution to partials within Slate found?

Thanks,
Tim

[jwalden1882]

Just want to second this discussion. I have over 300 API calls divided into a dozen categories. Would love to include master category files that each include the appropriate set of API calls named as individual files. This would make them much easier to find and maintain over time. Currently I have to combine all the calls within each category into a single file. Can still include the separate categories as individual includes, but each has 30+ calls in it.

[aarif4]

Hi,

I took a look at this issue and found that partials work and are a good solution for multi-file documentation. To put it simply, you need to do the following to use partials:

1. Rename source/index.html.md to source/index.html.md.erb
2. In source/index.html.md.erb, use the following partials command:
   <%= partial "path/to/other/file.md.erb" %>
   (Note: the path is written relative to the source/ folder)
3. Create a markdown file called file.md.erb in source/path/to/other/file.md.erb and add all the info you wanted to segment from index.html.md.erb

This will essentially import the contents of file.md.erb to index.html.md.erb, which will be rendered and presented in Slate as usual.

Also, I've found partials to be pretty flexible with filenames; I could simply say "path/to/other/file" in that partials command and it will find it, regardless of extension details. As a result, you could potentially not need to worry about what extension to use on the sub-files since they'll be imported to index.html.md.erb, which has the proper extensions.

If you take a look at my forked repo here, you'll find that I made a commit to enable this feature. In there, I made a nested file structure in source/sections where each section/chapter in my API had its own individual master file in its own folder (e.g. sections/introduction/master, sections/authentication/master, etc.). Anyway, check it out if you're looking for a good example of partials in Slate.

Hope this helps!

---

Edit:

@janicecmt, if I understand your comments correctly, you:

1. Have the following file structure in your working copy of Slate:

├── source
|   ├── index.html.md
│   ├── includes
│   │   ├── _foo.md
│   │   ├── partial3.md.erb
│   │   └── _partial4.md.erb
│   └── master.md.erb
└── partials
        ├── partial1.md.erb
        └── _partial2.md.erb

2. You reference _foo.md in index.html.md using the includes directive
3. In _foo.md, you use partials like so:

<%= partial "../partials/partial1" %>
<%= partial "../partials/partial2" %>
<%= partial "partial3" %>
<%= partial "partial4" %>

If all of that is true, then this is what you would need to do in order to use partials in your working copy of Slate:

• Change _foo.md's extension to _foo.md.erb. This is because you are using partials in that file. In other words, changing index.html.md to index.html.erb isn't useful because there are no partials being used in index.html.md in the first place
• When using partials, write the path of each partial file with respect to source/ directory. For whatever reason, I found that to work in my tests with partials. Therefore, foo.md.erb should have the following contents:

<%= partial "partials/partial1" %>
<%= partial "partials/partial2" %>
<%= partial "includes/partial3" %>
<%= partial "includes/partial4" %>

It's obviously been a few years since you've come across this problem. Hope this helps you tie up some loose ends.

---

Edit 2:

@nzkozar Thank you for pointing that out, totally missed that. Fixed :)

[nzkozar]

@aarif4 You have a typo in your post, which just led me on a 30min debugging adventure.
In your 2nd step (beginning of the post) you wrote <% partial where it should in fact be <%= partial as you have correctly written in the rest of the post. Please correct, so that others don't experience the same as I did :)