content: Document versioned module imports

[jmooring]

See gohugoio/hugo#13966.

For example:

[[module.imports]]
  path    = 'github.com/bep/hugo-mod-misc/dummy-content'
  version = 'v0.2.0'
[[module.imports]]
  path    = 'github.com/bep/hugo-mod-misc/dummy-content'
  version = 'v0.1.0'
  [[module.imports.mounts]]
    source = 'content'
    target = 'content/v1'

See:

• modules: Improve error checking and messaging hugo#14010 (comment)
• modules: Add support for direct version module imports in hugo.toml hugo#13966 (notes)
• https://gohugo.io/configuration/module/#version
• https://discourse.gohugo.io/t/mounting-different-branches-tags-from-the-same-repository/55849/8

Also, provide example where version isn't v0.x.x or v1.x.x, e.g.

[[module.imports]]
path = "github.com/alex-shpak/hugo-book/v12"
version = 'v12.0.0'

In the above note that the path suffix must exist for v2 and later, and it must match the major version of version.

Maybe document this handy command too:

$ go list -m -versions github.com/CaiJimmy/hugo-theme-stack/v3
github.com/CaiJimmy/hugo-theme-stack/v3 v3.0.0 v3.1.0 v3.2.0 v3.3.0 v3.4.0 v3.5.0 v3.6.0 v3.7.0 v3.8.0 v3.9.0-alpha v3.9.0 v3.9.1 v3.9.2 v3.10.0 v3.11.0 v3.12.0 v3.13.0 v3.14.0 v3.15.0 v3.16.0 v3.17.0 v3.18.0 v3.19.0 v3.20.0 v3.21.0 v3.22.0 v3.23.0 v3.24.0 v3.24.1 v3.24.2 v3.25.0 v3.26.0 v3.27.0 v3.28.0 v3.29.0 v3.30.0 v3.31.0

[bep]

A side note here, the example you note is good, but I would probably do:

[[module.imports]]
  path    = 'github.com/bep/hugo-mod-misc/dummy-content'
[[module.imports]]
  path    = 'github.com/bep/hugo-mod-misc/dummy-content'
  version = 'v0.1.0'
  [[module.imports.mounts]]
    source = 'content'
    target = 'content/v1'

To demonstrate what I would recommend as the common pattern: Have a the latest version mounted to content and upgradable via hugo mod get and then have archived versions pinned with version. There's certainly arguments for having the above, too, of course.

[jwr0]

Following up on the discussion from gohugoio/hugo#14010 (comment), since this comment is specifically about the docs...

The docs currently mention this:

If set to a version query, this import becomes a direct dependency,

A user of hugo who isn't also a golang developer might click that link, look at the semver examples such as "A fully-specified semantic version, such as v1.2.3", and they might think to themselves "oh, that looks like a git tag." Then they go lookup the GitHub of whichever community module they want to use, they find the desired version tag, and they paste it into their yaml config.

But what they wouldn't know just from reading the docs is that a git tag, on its own, isn't the only thing required to make the version pin work. The open source project that they are consuming also has to be set up with some kind of metadata or something to make it work. The examples in this comment show the contrast between an open source project which does have the required metadata (docsy) versus another project that doesn't (PaperMod).

It would be helpful to the users who aren't golang developers if the docs stated something like "if you want to pin a version, the open source module that you are consuming specifically has to support that, and not all of them do. Go to their GitHub and look for XYZ file to see if they have support for this. And if the module you are consuming doesn't support proper versioning, you can pin a commit hash instead."

Thanks to @jmooring for helping me understand a tiny bit of this stuff, as I myself am not a golang developer.

[bep]

@jwr0 I suspect you're overcomplicating things. I have tested this before (and just did some more tests now), and the version query in version works as expected for me even when importing Git repos without go.mod. I even tested incrementing to a new major version in a non-go-mod-repo, and that also works fine.