Using json vs converting to markdown

[FraZ]

I’ve been reading up on Hugo and I have tinkered with it in the past to get a prototype running related to my question, but as my understanding of Hugo grows, I feel like my original approach is needlessly complicated. I was hoping you could give me some advice on how to approach my challenge.

I work in software development and my company writes their specifications in Gherkin (typically known as .feature files). Not everything is written in Gherkin though: we also have Markdown files that contain information that do not fit the Gherkin format. My goal is to generate a static website that contains all of the documentation for a specific piece of software in an easily digestable way.

In my initial attempt, I converted the .feature file into Markdown, which included using shortcodes and default Markdown syntax. It worked, but learning about Hugo supporting JSON made me think of an alternative…

Instead of converting it to markdown directly, convert the .feature file to JSON, and only use markdown files to define - through frontmatter variables - which of the available .feature file should be displayed as part of the content. All of the logic to generate the actual page would be in a shortcode / partial / template of sorts.

The main benefit I see is a very clean separation of concerns: my own custom tooling only has to worry about the data and its structure, and I can leave all of the heavy lifting when it comes to rendering to the tool that is actually designed for it.

Does this sound like a solid idea? If so: what pointers would you give me on how to achieve my goal? Some general directions or inspirational examples would already help a ton. If not: can you explain why you would argue against it, and what alternative approach you would suggest?

Thanks in advance!

[jmooring]

After converting your feature files to JSON, if the JSON contains a field that could be mapped to the content title, you could use content adapters and completely bypass markdown.

If that’s not feasible, you might consider organizing your content into leaf bundles, with the JSON file logically associated with its matching markdown file:

content/
├── products/
│   └── product-1/
│       ├── feature-1/
│       │   ├── feature.json
│       │   └── index.md
│       └── feature-2/
│           ├── feature.json
│           └── index.md
└── _index.md

That way you don’t have to include a front matter field pointing to a JSON file somewhere… the JSON file is in the same directory as the markdown file, and is available as a page resource.

[FraZ]

I think I can do that mapping of content to content title, so I think those content adapters are the way to go. Time to learn more about all those new concepts! Thanks!

[FraZ]

OK I’ve done some tinkering and googling and I think that - at least in part - this is due to me not properly understanding how content is/should/can be structured and how it relates to navigation. So let me elaborate a bit more on what I am trying to achieve, and what makes my brain explode at the moment.

So let’s take a simple example, lets say that I want to document the workings of a calculator I built. What I would like to end up with is a website that contains the following navigational structure:

• Introduction
• Functional overview
• Addition
  • Manual for usage
  • Specified behavior
  • Known restrictions
• Subtraction
  • Manual for usage
  • Specified behavior
  • Known restrictions

Where everything but the specified behavior pages would be plain markdown, and the content of the specified behavior page should be retrieved from the appropriate feature.json (because I think each feature will become its own json file.

In my head, the content folder would match the navigation structure. So my brain defaults to the - probably very wrong - content structure of:

content
├── introduction.md
├── Addition/
│    ├── manual_for_usage.md
│    ├── known_restictions.md
│    ├── specified_behavior/
│        ├── addition.json
│        └── index.md
├── Subtraction/
│    ├── manual_for_usage.md
│    ├── known_restictions.md
│    ├── specified_behavior/
│        ├── subtraction.json
│        └── index.md

As you can see, my brain immediately moves towards leaf bundles, where I would use a shortcode in the index.md, like {{< feature-to-md "addition.json" >}} and then write the conversion as part of that shortcode.

The reason I would opt for shortcodes is that I can’t use a layout, because lay-outs are selected based on where the content is located, which would mean I would be using the location of data as both a navigational element, as a way to classify the type of content itself.

And that is where my brain breaks, which also explains why I veered away from content adapters: afaik, dumping all of the “features” in a single content folder, and generating pages within that folder breaks with the way I want to structure data towards my readers. Because they are not interested in “a list of all features”, but they are instead interested in “a list of all information related to addition”, which could (and does, in my example) include data that is stored in standard markdown files.

I’m struggling with describing my issue properly, so I hope I did a proper job. But to help, here are my core questions:

With this new information on my goal, and taking into account my level of experience, do you still recommend using content adapters?
…And if so, how do I solve the challenge regarding navigation (or what is the thing that I am misunderstanding that causes me to think that this will not work)?

Regardless of your recommendation: would the way I apply leaf bundles also work?
…Or would you suggest using leaf bundles in a different manner, and if so, how?

Am I understanding the purpose / application of how content is structured correctly?
I.e. It’s a way to classify data, and apply specific lay-outs based on it’s class, similar to how your example classifies data into either “books” or “posts” and applies different lay-outs to each… But also doubles as a way to nagivate your site.

[jmooring]

@FraZ

lay-outs are selected based on where the content is located

That is correct, but you can also specify layout and/or type in front matter to target a specific template.

Or you could conditionally perform the JSON->HTML conversion if the page bundle has a JSON resource.

I would try to avoid using a shortcode if possible; it’s just one more moving part.

There are a lot of ways to approach this. If I were you I would create a small prototype using the content structure above.

[FraZ]

Based on your advice I ended up going for an approach with leaf bundles and using the layout and type variables in the front matter to select the proper template and then use:

{{ $data := .Page.Resources.Get "feature.json" | transform.Unmarshal }}

To load the json data into the template

[jmooring]

You might be able to avoid a separate template by doing one thing if feature.json exists, and do something else if feature.json does exist. I’m a firm believer in avoiding unnecessary front matter whenever possible.