Existing repo/md files and Hugo

support
1

In short, I have an existing api/repo and I want to integrate a nice wrapper to the existing .md files (documentation). My repo structure (locally anyway) is

repo/
README.md
docs/ (all of the existing API/Service docs that BE engineers contribute to)
site/ (the site generated by Hugo)
src/ (all of the existing source code for the project we’re documenting)

My question is simple … am I able to link to and easily display .md files from docs/ inside of the Hugo app? I tried to link using relative url paths and I get REF_NOT_FOUND: “…/docs/md_file_to_render.md” …

I feel silly asking this, but I’m trying to find the easiest way to leverage all of the existing markdown files, without imposing or polluting the existing repo/codebase and requiring extra management or duplication of the documentation files. If that makes sense?

Any guidance is appreciated.

Also, I’m posting this to GH Pages eventually, and symlinks are not allowed … I don’t believe.

Dale

2

I had a little problem understanding it, so maybe not super simple.

In a recent Hugo version we added “module mounts”, which means, as one example, that you can mount any folder (and as many folders as you want) into the /content (which is the “virtual folder” where Hugo looks for content files). The docs should have the details.

3

Thanks for the quick reply. I feel like others would think it’s simple … :slight_smile:

I can look at module mounts … basically, I have a # of existing repos/projects that have a docs/ directory with .md files that engineers will contribute to and tweak … I’d like to, without moving or duplicating those files, display them nicely in the Hugo site and that means having a way to reference or link to them from within the site/content … and that’s where I got lost. :smiley:

Hopefully that clarifies a bit. Thanks again …

4

It’s probably harder without a concrete example.

Sure, but in my head that means you first need to mount all the repos’ /docs folders below the same root. They will form a union file system so you can mount them on top of eachoter if that is what you want. They would then all live relative to eachother when doing reflinking etc.

1 Like
5

I can add that you will probably want to read all of the documentation on Hugo Modules, which I suspect is a good fit.

1 Like
6

Interesting. It looks as though it should work, but there’s not many examples of the module mount use or what you should see in public/content/{mount} … as an example … I have “…/docs” which is one level up from my site directory, mounted to “content/docs” … and if you ‘Hugo -D’ to build … you see content/docs/index.html and index.xml … but if I try to access the files via a link, you get a 404 and a warning on the command about a missing layout HTML for “page” … maybe I’m missing something? The concept makes sense … but not the result I’d hoped for.

7

Hi there,

It would be much easier to get help with a sample repo to play with. If you can’t publish your actual code, make a dummy one with sample structure/content.

3 Likes
8

Hi,

this is how I use modules (including markdown content files from any folder of a public repo):

# config.yaml
module:
  imports:
    # My custom/project Hugo theme
    - path: custom
    # Default partials and shortcodes I use for all Hugo projects
    # (no more copying and pasting necessary)
    - path: ../../../hugo-themes/default-hugo-theme
    # Import a public repo
    - path: github.com/zwbetz-gh/uswds-hugo-theme
      # Only use what you need
      mounts:
        - source: layouts/shortcodes
          target: layouts/shortcodes
        - source: exampleSite/content
          target: content/new

Then just run hugo mod init test.

Maybe it helps!

2 Likes