Deduplicate information across index.md and README.md

[kevinlin1]

I noticed that some information is duplicated across the index.md and README.md files in the Just the Docs Template, and some information is not listed on both pages. I wanted to open this issue so that we might be able to discuss an approach for combining these two files.

Potentially desirable end state
Combine the information currently spread across index.md and README.md into a single file, README.md, that is permalinked to /:path/. The context for this suggestion was something that I did last year to deduplicate information across the index.md and README.md files in my Just the Class template. I figured this might also be a useful change for the official template repository too.

The advantages of deduplicating information in these two files:

• Make things less confusing for users who mistakenly change README.md when they intend to change index.md.
• Display of all key content upfront in GitHub, which renders the README.md using GitHub's markdown engine.
• Aid maintainers and users of the template repository by reducing the need to update or other synchronize changes across both files.
• Fix an issue with the template website currently generating a publicly-visible plain page for README.md. (This can be excluded in the Jekyll site configuration.)

The drawbacks of deduplicating information in these two files:

• YAML front matter is slightly annoying to read for people who aren't interested in it, but I figured this was an okay annoyance since it's the template repository and not the gem source repository.
• Make things more confusing for users who want their README.md (displayed in GitHub) to appear separately and differently from their website index.md content.

What are your thoughts? My assumption is that having a unified README.md and index.md makes things clearer for less-experienced users by ensuring that a change to a file that looks like the home page's content would in fact result in a change in the output website.

[mattxwang]

Hi @kevinlin1, thanks for submitting this issue (and being quick to upgrade just-the-class to v0.4.0).

I certainly agree that the duplication could be a maintenance burden and/or be confusing. To be honest, I haven't put as much time into this template compared to other theme work, and this is a good reminder to spend some time on it!

I believe that there was an original intention to separate the two files. In #5 (the PR writing these files), Peter listed:

• Updates the home page at index.md to give an overview of what the template can do.
• Updates README.md to focus on how to do it

I think this also makes sense; in my experience, the README for a repository is a short and concise document that only describes how to start development (and/or deploy). From my perspective, READMEs are not intended to be user-facing (where the user is a visitor of the website), and it may be good to push users of our theme to separate the README from rendered materials.

If he has time, I'd also like to tag in @pdmosses if he has any additional thoughts; he's always done a great job with identifying clear and concise documentation.

---

For what it's worth, I am personally okay with:

• keep the current configuration, but adjust our documentation/framing to make things more clear
• move forward with Kevin's suggestion; I wonder if we can do something to avoid most of the front matter items

I don't have a strong opinion, though perhaps I'm leaning slightly towards keeping what we have. However, I'm not wedded to that opinion, and am happy to move forward with other community members' ideas!

Separately, I agree that excluding the README (or, explicitly rendering it) is a good idea; the current limbo state is not great.

[pdmosses]

I basically agree with what @mattxwang wrote. I still regard README.md and index.md as having separate (albeit related) purposes.

I wonder if we can do something to avoid most of the front matter items

I think we could entirely eliminate the front matter in index.md using defaults in _config.yml (or a couple of plugins).

However, the GitHub/GFM rendering of our current index.md is really ugly. JtD users should surely ignore the GitHub page and read the properly rendered home page on our website. I generally try to avoid browsing source code on GitHub.