What is the role of docs

[VincentTam]

The project owner says that docs is generated from exampleSite in #85. The generated HTML source code is once again posted in a separated GitHub repo "introduction". I find that a bit complicated. I wonder why GitHub's built-in gh-pages branch is not utilised for hosting the theme's demo site, unlike Octopress. Putting them in one single repo helps us focus better during code exploration.

In fact, Git is not made for tracking generated code.

Besides, after running hugo server ... to locally preview the demo site, two files were automatically generated under exampleSite/resources/_gen. I wonder why there're files tracked in that repo. When one creates a PR, one also needs to include the changes in that repo?

I am quite confused about these two folders with generated code. I would welcome any thoughts about this.

[hanzei]

https://github.com/vickylai/introduction is not longer used and should be removed.

What advantages do you see with using a gh-pages branch of the example site?

Besides, after running hugo server ... to locally preview the demo site, two files were automatically generated under exampleSite/resources/_gen. I wonder why there're files tracked in that repo. When one creates a PR, one also needs to include the changes in that repo?

These two files should not be checked it. There are generated in https://github.com/vickylai/hugo-theme-introduction/blob/master/layouts/partials/head/css.html depending of you using hugo or hugo server.

We check in exampleSite/resources/_gen because then people can just clone the repo and run it.

[VincentTam]

Thanks for your explanation. I've abandoned GitHub Pages for a year, and I've recently switched to GitLab Pages, so please excuse me for the question in the title, as well as the question about gh-pages branch. I've just realised that GitHub has changed the technical details, so that it's now possible to build GitHub pages from master/docs.

[hanzei]

I see that isn't not idiomatic to include the generated source of the example site in this repo. But I don't see an easier other way.

[hanzei]

I think the lesson learned from this is, that docs should not be regenerated by contributors. Every time we do a release we should update docs.

@VincentTam are you fine if I close this one?

[VincentTam]

👌