Add custom summary / excerpt feature

[zacbook]

This allows additional flexibility in creating summaries of posts on the homepage via the front-matter variable summary. I implemented this because, currently, Blogdown's processing of Rmarkdown files results in <!--more--> being left as an HTML comment in the output.

[kakawait]

@zacbook thank you for contribution i will check that tomorrow

[kakawait]

@zacbook You said

I implemented this because, currently, Blogdown's processing of Rmarkdown files results in <!--more--> being left as an HTML comment in the output.

But is there any a real problem to have HTML comment on HTML output? Or I miss something

[zacbook]

I should have been a bit better in explaining - it has more to do with the Summary not being generated correctly than the comment being left in the post. Basically, Blogdown doesn't process the <!--more--> comment to stop the Summary at that line, which makes text after that point appear on the homepage. If it would be helpful, I could pass along some examples.

[kakawait]

@zacbook if you have time to give me some examples I will appreciate.

I don't know Blogdown, but as I know <!--more--> is built-in Hugo feature thus I can't understand why it shouldn't work with Blogdown too since Blogdown is using Hugo.

---

I just saw it's not a isolate issue

rstudio/blogdown#142
rstudio/blogdown#92
rstudio/blogdown#21
rstudio/blogdown#164

It's seems to be an issue with .Rmd not .md that why I was not able to reproduce

---

Is not I don't want to accept PR but PR seems to be a workaround for an upstream issue that why I try to understand well before accepting, no offense.

[kakawait]

@zacbook What do you think about re-using existing metadata Description https://gohugo.io/content-management/front-matter/#predefined as @yihui explained in rstudio/blogdown#92 (comment) instead of creating a new metadata Summary?

[kakawait]

In other hand some other themes seems to support summary param rstudio/blogdown#21 (comment)

[zacbook]

It's definitely an issue with *.Rmd files and not *.md files. The *.Rmd files are processed by Blogdown (actually Knitr within R, then pandoc to create the html), but the *.md files are left to be processed by Hugo.

If you feel that it's not an issue with Tranquilpeak, but rather an issue with Blogdown, then my PR will still offer additional flexibility for Tranquilpeak users by being able to create custom summary text that does not appear in the main post. It's not a huge killer feature, but may be nice in some instances.

As to whether to use Description or Summary, I don't have a strong opinion. I'm a relative newcomer to Hugo, so it may be that Description is more well-established for this feature.

I added an example of the behavior on my webpage. The branch source-example contains my code, and the branch master-example contains the rendered html.

Hope that helps!

[kakawait]

@zacbook yes is not directly a Tranquilpeak issue but now i understand the issue and the context I think I will be acceptable PR.

In addition Blogdown reference that theme and I'm glad! So let's try to support both Hugo and Blogdown.

Now the only question is should we take description or summary param. firstly I have to check what is the current usage of description param.

Let me some days to do some research!

[zacbook]

Yes, your theme was highly recommended in the Blogdown docs (beyond it just being an awesome theme :).

Let me know if you come across anything that helps with the decision/summary choice. I can update my PR when you make a decision.

[kakawait]

@zacbook Let's go for Summary because Description should be use for other purpose.

Thank you for contribution I will merge it on develop, will be part on next release asap

[zacbook]

Awesome! Was there something you read that ultimately swayed you against Description?

[SteveRxD]

Hi, I hope it's OK posting questions on the end of the thread like this... can I ask what the conclusion is for someone who wants to include a shorter summary / excerpt for their .Rmd post? Should it be possible to just use a summary parameter? Because I can't seem to get this to work.... Thanks for your help.

[jhchou]

Another newcomer here, like @zacbook and @SteveRxD also coming here from blogdown / Hugo / Rmd. The tranquilpeak theme came highly recommended from folks in the blogdown sphere!

Like others, I discovered that <!--more--> doesn't work in Rmd documents processed by blogdown. I assume that the summary parameter is for a future beta release? I just started 2 days ago and have 0.4.3-BETA installed, but summary appears poised for release in 0.4.4-BETA. It will be very helpful when available, thank you!

[SteveRxD]

@jhchou if it helps, I got it working in the meantime by tweaking the HTML file as suggested by @zacbook (despite having no familiarity with HTML, and fearing that I would screw up the code). You can see exactly which changes to make by clicking on the 'files changed' button at the top of this thread.

To make the change, open the file themes/hugo-tranquilpeak-theme/layouts/_default/summary.html.

Then on line 43 change {{ .Summary }} to
{{ if .Params.Summary }} {{ .Params.Summary | markdownify }} {{ else }} {{ .Summary }} {{ end }}

This should then enable the summary: parameter to work in your Rmd document.

[jhchou]

@SteveRxD Haha! Seems like we did the same thing. I just posted elsewhere a very similar change:

@andrie -- thank you very much for the simple replacement solution for tranquilpeak to allow use of a description field in the YAML.

In case anyone finds this solution, for the current version 0.4.3-BETA, the replacement in themes\hugo-tranquilpeak-theme\layouts\_default\summary.html has been simplified a bit:

Replace line 43:

{{ .Summary }}

with:

      {{if .Description }}
        {{ .Description }}
      {{ else }}
        {{ .Summary }}
      {{ end }}

... but will use yours, as it seems that summary is going to be the preferred parameter.

Although, rather than replace the summary.html file in the themes folder, I thought it'd be better to create a /site/layouts/_default/ folder, and put the altered summary.html file in there, to override the theme version.

[zacbook]

Hey everyone! Sorry I'm late to the party - were you able to sort it out? If it never found it's way into master, I think I had this working in the development branch in my fork: https://github.com/zacbook/hugo-tranquilpeak-theme/tree/develop-zacbook Cheers, -Zac

…

On Sat, Apr 7, 2018 at 6:14 PM, Joseph Chou ***@***.***> wrote: @SteveRxD <https://github.com/SteveRxD> Haha! Seems like we did the same thing. I just posted elsewhere <rstudio/blogdown#21> a very similar change: @andrie <https://github.com/andrie> -- thank you very much for the simple replacement solution for tranquilpeak to allow use of a description field in the YAML. In case anyone finds this solution, for the current version 0.4.3-BETA, the replacement in themes\hugo-tranquilpeak-theme\layouts\_default\ summary.html has been simplified a bit: Replace line 43: {{ .Summary }} with: {{if .Description }} {{ .Description }} {{ else }} {{ .Summary }} {{ end }} ... but will use yours, as it seems that summary is going to be the preferred parameter. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#233 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/APehwwgcvF3SMzygaTgimIFyFa6kT-4Dks5tmWRngaJpZM4QcaHF> .

[SteveRxD]

@zacbook hi, yes we got it working using your code. Many thanks!

[rwanjohi]

Hi @zacbook, I am having the same issue with hugo-icarus-theme. I tried to follow the suggestions but cant seem to find the .Summary in summary.html. I am new to this, any help on this will be greatly appreciated. Thanks

[zacbook]

Hi, I'm not familiar with the icarus theme, but in order to use the .Summary variable, the theme would need to support it. Cheers, -Zac

…

On Mon, Apr 23, 2018 at 6:52 PM, rwanjohi ***@***.***> wrote: Hi @zacbook <https://github.com/zacbook>, I am having the same issue with hugo-icarus-theme. I tried to follow the suggestions but cant seem to find the .Summary in summary.html. I am new to this, any help on this will be greatly appreciated. Thanks — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#233 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/APehw3dFPtPtvgLOf7MXcchCIoRctokyks5troVDgaJpZM4QcaHF> .