Semantic file naming.

[kevinwolfcr]

I think in order to properly establish standards since the beginning, we should start naming semantically the chapters folder contents and their contents recursively.

This will be useful when automatically generating both pdf and html versions of the book, and will bring us some perks like:

1- Easy generation of TOC's files. 2- Properly structuring the book using simple conventions.

I've created a single file within each chapter named chapter-resume.md thinking on an introduction for each chapter, something like an excerpt.

Any thoughts @addyosmani @PascalPrecht @stephenplusplus?

[0x-r4bbit]

@kevin-wolf so you would create a file for each sub section from a chapter, am I getting you right?

[sindresorhus]

Definitely, an automatic TOC is a must.

[addyosmani]

+1 to all of the above.

[kevinwolfcr]

@kevin-wolf so you would create a file for each sub section from a chapter, am I getting you right?

@PascalPrecht yes, that's the idea, create each sub section of the chapter in a single file within the chapter folder prefixed by an id, we can even use yaml-front-matter if we want to add some meta data to a chapter. That makes sense for you?

Definitely, an automatic TOC is a must.

For sure, @sindresorhus, with this approach we will be able to easy generate TOC, as well as the site will be SEO optimized, we can use a single url by chapter, etc.

+1 to all of the above.

Thanks, @addyosmani. I will try to create a new branch, write a few examples and make a PR, in order to show you a first working example.

Cheers to all :).

[tomByrer]

Great ideas!

[michealbenedict]

My initial motive for toc.md was to help structure chapter specific contents. I do prefer this idea over the use of toc.md.

@kevin-wolf, Can i propose keeping the content structure for tools as proposed in https://github.com/tooling/book-of-modern-frontend-tooling/issues/9#issuecomment-31270166? It would be great to have a canonical way of talking about each tool.

[kevinwolfcr]

@kevin-wolf, Can i propose keeping the content structure for tools as proposed in #9 (comment)? It would be great to have a canonical way of talking about each tool.

Yes, you can have as many files as you want, that's the magic behind! :). The idea of prefixing a file by a number its to make the compiler know the order of the files.

[Plou]

A downside of this approach is a change in the chapter's order make you edit many files. Where a TOC.json file, used to build the book, may be easier to maintain and allow to edit the order without "commiting" on the content files.

[kevinwolfcr]

I like your approach @Plou, seems to be more flexible, thanks. @addyosmani @PascalPrecht @sindresorhus what do you guys think?

[michealbenedict]

@Plou the current commit contains toc.md in each chapter. The goal was to use this file to parse the order of the content via grunt tasks and respectively generate content.

Under the assumption that the order of topics would not change very often, I found @kevin-wolf 's suggestion to file-naming much structured. Would you disagree @Plou?

[sindresorhus]

I like filename ordering, that way it's in correct order when looking at the files too.

[Plou]

File ordering is nice, I agree with you.

[addyosmani]

Let's shoot for file ordering. It would be nice to finally nail down an initial structure that we can recommend for pull requests coming in for content.

[0x-r4bbit]

@addyosmani exactly. Would be great if we already could consider a defined structure.

[kevinwolfcr]

And for building the web site, I recommend using Assemble.io, or we can build a simple Gruntfile which will load the markdown files and pass an object to jade views, I can improve modelify in order to make it compatible.

[0x-r4bbit]

@kevin-wolf Are these tools also compatible with other outputs? Like generating pdf, mobi or rtf?

[kevinwolfcr]

@PascalPrecht the tool generates a JSON objects from a source input. We can handle that JSON object as we want.

[sindresorhus]

I don't think we need something heavyweight. How about a gulpfile with a few plugins?

[kevinwolfcr]

:+1: on the gulp approach.

[0x-r4bbit]

Yea but still, gulp plugins also just rely on other tools that do the actual job.

[michealbenedict]

Referencing https://github.com/tooling/book-of-modern-frontend-tooling/pull/31#issuecomment-34026258 on why the table of contents based approach made more sense over semantic file naming. Let me know if there are any thoughts/concerns.