Somehow sync repo README and doc index.md?

[tpolecat]

I'm finding that I want my repo's README and the index page for my microsite to be the same modulo front matter. This would be easy to hack up … would this be useful or am I just being weird?

[juanpedromoreno]

Hey, thanks for mentioning it. If I didn't misunderstood, actually that functionality is already implemented. For example:

https://github.com/typelevel/cats/blob/master/build.sbt#L138
https://github.com/typelevel/scala/blob/typelevel-readme/build.sbt#L12

You could ignore the index.md file that is automatically copied to the docs folder (since it'll be copied each time you call makeMicrosite and maybe it doesn't make sense to commit it):

https://github.com/typelevel/cats/blob/master/.gitignore#L22

[tpolecat]

Oh right, perfect. That's it! 👍

[tpolecat]

Well. Not quite. Because it has no front matter it doesn't get included in the site. I'll think about it. No need to reopen.

[gpampara]

@tpolecat I just had the same issue and solved it, crudely, as follows:

1. Use micrositeExtraMdFiles to copy the README.md file to a file called README.content
2. Create an index.md in the src/main/tut directory, which then contains the YML front-matter, with a liquid template for jekyll that simply includes the content of the content of README.content in the file. The resulting index.md is then something like:

---
layout: home
title: "Home"
section: "home"
---

{% include_relative README.content %}

It's perhaps not the cleanest solution, but at least I can get my readme content into the site without too much complication.

[juanpedromoreno]

Thanks @gpampara for sharing it!

Do you think we could automate it somehow?

[gpampara]

I guess one could automate this. This would mean that the README would become the main page of the site though? Good? Bad?

It works well for my use at the moment and I don't really see any glaring downsides, but I guess the option to override this behaviour would be reasonable. Suppose this would warrant another config option? Or it could be that if the user provides an index.md, then the behaviour of using the README would be disabled?

[tpolecat]

An option to make the repo README become the landing page for the site sounds great to me. Until then I may use @gpampara's hack. Thanks Gary!

[tpolecat]

Reopening because it seems like a thing.

[juanpedromoreno]

What do you think if we rewrite the extra md file configuration in the following way?

case class ExtraMdFileConfig(fileName: String, layout: String, metaProperties: Map[String, String] = Map.empty)

val micrositeExtraMdFiles = settingKey[Map[File, ExtraMdFileConfig]](
    "Optional. The key is related with the source file, the map value corresponds with the target relative file path and the document meta-information configuration. This key is useful for those document files that are located in a different places from the tutSourceDirectory. By default, it's empty")

// Example:
micrositeExtraMdFiles := Map(
	file("README.md") -> ExtraMdFileConfig("index.md", "home"),
	file("CONTRIBUTING.md") -> ExtraMdFileConfig("contributing.md", "page", Map("title" -> "Contributing", "section" -> "contributing", "position" -> "5")),
)

This configuration might generate the following files (in the docs folder):

• index.md:

---
layout: home
---

<README.md contents>

• contributing.md:

---
layout: page
title: Contributing
section: contributing
position: 5
---

<CONTRIBUTING.md contents>

Does it make sense?

[gpampara]

Yeah, that's a decent and reasonable approach. Keeps it consistent with the rest of the page definitions.

[gpampara]

The new scheme works well, thanks :)