Make external tutorials a first class citizen

[bep]

Like this:

https://forestry.io/blog/build-a-json-api-with-hugo/

We need a better way to link to those -- a standard way, more visible.

Which describes custom output formats much better than I did when I wrote the first version of the one on gohugo.io.

And @regisphilibert

If that doesn’t work, you may have to stop and restart the Hugo server.

I think the correct advice would be to run with --disableFastRender. But I kind of don't understand it. The liverload doesn't work for JSON -- but a CTRL + R should?

[regisphilibert]

You are right, refresh is pointless without --disableFastRender
But using --disableFastRender I still have to CTRL + R to update the changes, is that normal?

I'll ask Forestry to update the post with your suggestion.

[bep]

1. I don't think --disableFastRender should be needed. We should be smart enough about it. That sounds like a borderline bug and should be fixed.
2. Livereload is injected JavaScript .... which is HTML only.

I know we are pretty smart about live-reloading changes in JSON and images etc. inside bundles ...

[regisphilibert]

Alright, the post has been updated.

Back to original topic, I think it could be very helpful to add at the end of a documentation page a very short selection of "good reads" which dive in detail into the given topic/feature.

I think it may be more efficient into helping users than adding yet another section to the doc site listing good reads unrelated to each other.

@budparr I wonder if you have design ideas, suggestion from other sites?

[budparr]

I don't see anything wrong with linking to things at the end of a post, but there's a risk that outside posts go stale or disappear (having collected hundreds of links over the years, I can you can count on that. That was partly why I suggested "guides" where tutorials can be curated.

They're not mutually exclusive, of course, and something like the post at Forestry would not be appropriate as a guide. Nonetheless, we definitely need to get people more how-tos and clear examples, that's the number one thing I hear from people.

[bep]

I don't see anything wrong with linking to things at the end of a post,

I was more thinking in the line of a "see also" box in the middle somewhere, i.e. near the relevant section. I have done it in one or two places with the "note" shortcode, but I feel it gets a little bit buried.

[budparr]

So it could be as simple as this (perhaps but in a box to draw attention to it, or perhaps not).

The articles could be listed in front matter, or perhaps collected in a data file and related back using tags.

[budparr]

I think better in a data file then related back. That seems more manageable and makes articles useful on more than one page.

[bep]

I think better in a data file then related back. T

No, my gut feeling is still a shortcode, e.g. 1 link to a relevant article inside a section/paragraph.

[regisphilibert]

No, my gut feeling is still a shortcode, e.g. 1 link to a relevant article inside a section/paragraph.

Yes I see your point. Beside it allows the editor to add a short sentence describing how this reference can help the user at this point in the doc.

[budparr]

Then what's needed beyond this?

[kaushalmodi]

@budparr This came up earlier in a separate thread too. I believe that data files are a better way to do this. That way you have a single point of controlling all external post references, rather than going within each doc file and manually adding it.

The data file can have a simple structure like:

[doc-page1-basename]
  # page 1 ref 1
  [[doc-page1-basename.ref]]
    author = "Foo Bar"
    title = "Ref post's title"
    url = "https://awesome.ref/"
    date = "2018-04-13"
    hugo_version = "0.38.2"
    image = "Featured banner image for the post.. may be?"
    summary = """
    Interest-invoking a bit detailed summary.. may be a line or two 
    telling the readers why they might find that external ref useful.
    Can contain **Markdown** too.
    """
  # page 1 ref 2
  [[doc-page1-basename.ref]]
  ...
[doc-page2-basename]
  # page 2 ref 1
  [[doc-page2-basename.ref]]
  ...

Then in the single.html or equivalent for the doc site pages, you simply check if index contains .File.BaseFileName (or may be the top portion of .File.Dir if the doc file is a page bundle..), then then range through that.

Single point of control

• Easy to add new references for any page in the doc site
• Easy to delete/modify too, in the event some link goes stale.
• Consistency!

[regisphilibert]

I think the shortcode vision works great because, the post in question may not be about the whole page presently being read by the user.
Some post may only focus on one method or one particular usage of such method.

In this sense, we should design a sort of unique note shortcode which would provide at a glance, reasons for why the reader could or could not benefit from reading the post. I am no designer :( but something along:

---

Read on

For more information on how to use whatever in such context.

📑 Link

---

Read on

• Practical examples
• Tutorial

📑 Link

[budparr]

I definitely see your point. The two approaches aren't mutually exclusive, but ultimately, we just need to find ways to make more concrete examples available and give users an easy way to find them.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If you still think this is important, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.