search

gohugoio / hugoBasicExample

MIT License
281 stars 281 forks source link

Hugo documentation duplicated here #7

Closed MarkDBlackwell closed 5 years ago

MarkDBlackwell commented 8 years ago

The example content source code incorporated here is a snapshot (taken two years ago) borrowed from its canonical location in spf13/hugo.

As I'm aware, Hugo's showcase of themes (spf13/hugoThemes) is generated by a shell script resident in repository spf13/generateThemeSite. Repeatedly (and desirably), Hugo's theme showcase presents the same default content, each time utilizing a different theme.

If any theme lacks its own example content (in its own directory exampleSite/content), the example content from this repository supplements it in the showcase (as this shell script line reveals).

For a showcase to present content repeatedly is good in many ways. However, here, apparently—in practice—some setup detail has led many themes to:

When we look at a particular theme in the showcase, it makes no visible difference whether the identical content is:

Arguably, the combination of borrowing and incorporating content into this repository, and then presenting it automatically in Hugo's theme showcase (rather than simply referring to it):

In a repository, incorporating borrowed Hugo documentation source code IMO is a bad thing—when we consider Hugo's presumed overall goals of keeping its documentation (found anywhere in the wild) up to date (as far as possible) and improving it.

Since this repository—along with some of the themes—is providing obsolete content in the showcase, it seems likely that people sometimes will read it. For people to read obsolete documentation in general IMO is undesirable for them, and for us.

For example, when we look at hugo-cactus-theme in the showcase, we observe that the creating-a-new-theme.md document (in its example site) is outdated, compared with Hugo's current copy of the same document.

Incorporating copies of documentation source code into other repositories isn't something people naturally do. However, once a piece of documentation source code has escaped "into the wild" (i.e., is copied into other repositories, due to people being encouraged to do so), it's extremely difficult—naturally—to keep it up to date (in those copies).

This problem should be corrected IMO sooner rather than later, before the increasing number of Hugo themes further worsens the problem.

Perhaps this example content would be better as Lorem ipsum text? Or would it be better if the shell script automatically copied this example content from spf13/hugo each time it runs?

Which solution is preferable (or perhaps another)?

Presently, Hugo's user base seems large enough to benefit from such a change. And this repository IMO seems the best place to start.

Currently, nineteen (19) repositories (beyond this one) have incorporated some of the spf13/hugo documentation source code. The problematic theme sites are:

Here are some references (for your enjoyment):

MarkDBlackwell commented 8 years ago

@digitalcraftsman I've extensively rewritten the above issue. Would you please take another look, and give me the benefit of your thoughts? :)