search

google / docsy-example

An example documentation site using the Docsy Hugo theme
https://docsy.dev
Apache License 2.0
472 stars 686 forks source link

Alternative way to install docsy repo into themes #6

Closed kaycebasques closed 5 years ago

kaycebasques commented 5 years ago

I find git submodules to be really weird. Just a suggestion on a different way to handle the initial setup for the repo.

Ignore the themes directory in .gitignore:

themes
...

Create a package.json:

{
  "name": "docsy-example",
  ...
  "scripts": {
    "install": "cd themes && git clone git@github.com:google/docsy.git"
  },
  ...

Instruct users to run npm install when setting up the docsy-example repo.

LisaFC commented 5 years ago

The main problem with not using submodules is that it's harder to pull in the latest version of the theme, especially if it's been modified a lot from when you cloned it. It was very easy for me to update this project to point to the theme version with your feedback widget, for instance - just git submodules update --remote in my local copy.

Cloning the theme works fine, of course, but getting it as a submodule is the Hugo recommended approach for most cases.

LisaFC commented 5 years ago

BTW I agree that submodules are weird but they're probably more bewildering for the theme author than the theme user, once you know that a)this is pointing to the theme repo at a specific revision and b)you can run this command to make it point to the latest version, it's pretty trivial. The one real issue you can run into with this particular theme is that it has submodules so you need to recurse it if you want to work with it locally.

kaycebasques commented 5 years ago

Seems like reasonable arguments for keeping things as is. I'll close this issue.