Update README.md

[pdmosses]

Major update:

• Refer to just-the-docs-template for getting started.
• Avoid duplication of details provided in the template README.
• Distinguish between theme users and theme developers.
• Augment the items for submitting code changes
• Make the marked-up text easier to read and edit by using short-cut link references.

See also the closely-related PR #1018.

[mattxwang]

Thanks! Appreciate you calling out that you don't need to fork the repo, I think that's one of the more confusing approaches.

Before I merge - I do think it would be good to still have docs for using JTD as a gem in the README - this is standard for any gem. What are your thoughts?

[pdmosses]

Before I merge - I do think it would be good to still have docs for using JTD as a gem in the README - this is standard for any gem. What are your thoughts?

I'm not familiar with the broader Ruby/gem ecosystem. I was thinking that anyone who wanted to start using the theme would be happy to use the template to create a fresh repo, instead of needing to set up Gemfile and _config.yml themselves. If they want to add a website using the theme to an existing repo, they could copy the contents of the new repo to their docs folder (then delete the repo created by the template). I hadn't imagined other ways of using the theme gem.

Anyway, I think you're suggesting retaining the following part of the original README.md:

Alternatively you can install it as a Ruby Gem.

Add this line to your Jekyll site's Gemfile:

gem "just-the-docs"

And add this line to your Jekyll site's _config.yml:

theme: just-the-docs

And then execute:

$ bundle

Or install it yourself as:

$ gem install just-the-docs

Alternatively, you can run it inside Docker while developing your site

$ docker-compose up

Provided that it comes after the suggestion to use the template, I don't mind adding that back in. Should I do it in my PR branch before you merge? You're of course welcome to edit my branch if that's easier for you.

[pdmosses]

Before I merge - I do think it would be good to still have docs for using JTD as a gem in the README - this is standard for any gem. What are your thoughts?

I've now restored the original section on using RubyGems.

[mattxwang]

Ah, sorry - personal stuff ended up getting in the way of things. Meant to respond earlier that I would be fine swinging either way, but I'm also happy with what's on the branch now; thanks for being proactive with both this and responding to other issues and discussions. I know I keep on saying this, but I actually should be able to write some sort of migration guide and wrap up actionables this weekend!