New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make external tutorials a first class citizen #449

Closed
bep opened this Issue Apr 13, 2018 · 14 comments

Comments

Projects
None yet
4 participants
@bep
Copy link
Member

bep commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Member Author

bep commented Apr 13, 2018

  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

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Contributor

budparr commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Member Author

bep commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Contributor

budparr commented Apr 13, 2018

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

screen shot 2018-04-13 at 5 50 54 pm

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

@budparr

This comment has been minimized.

Copy link
Contributor

budparr commented Apr 13, 2018

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

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Apr 13, 2018

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

This comment has been minimized.

Copy link
Contributor

budparr commented Apr 13, 2018

Then what's needed beyond this?

screen shot 2018-04-13 at 6 19 11 pm

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Apr 14, 2018

@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

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Apr 18, 2018

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

This comment has been minimized.

Copy link
Contributor

budparr commented Apr 18, 2018

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 comment has been minimized.

Copy link

stale bot commented Nov 29, 2018

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.

@stale stale bot added the Stale label Nov 29, 2018

@stale stale bot closed this Dec 29, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment