r-lib / hugodown Goto Github PK

Hugo has a way to preview the site locally, and this method typically shows all future dated posts and those with draft: TRUE in the YAML.

See docs here:
https://gohugo.io/getting-started/usage/#draft-future-and-expired-content

With hugodown, using the combination of server_start() and knitting to hugodown::hugo_document(), I'm unable to preview any draft or future content locally.

blogdown's docs on this:
https://bookdown.org/yihui/blogdown/local-preview.html

e.g. [tourmaline] and other links.

Not a very original idea. 😁

I really like

• https://rstudio.github.io/distill/blog_workflow.html (since Hugo has drafts too, there are two common possibilities, using drafts, and using git branches)

• https://twitter.com/apreshill/status/1108005028067835904

• https://www.garrickadenbuie.com/blog/blogdown-netlify-new-post-workflow/

I'm working inside an Academic site created from create_site_academic(). This doesn't work:

> use_post("post/plainmd", kind = "default")
Error: [ENOTDIR] Failed to search directory '/Users/alison/rscratch/test-hugodown/content/post/plainmd': not a directory

But if I make a new folder called default, and copy the default.md archetype into that folder and rename it index.md, it works:

> use_post("post/plainmd", kind = "default")
● Modify '/Users/alison/rscratch/test-hugodown/content/post/plainmd/index.md'
adding created directory to watchlist /Users/alison/rscratch/test-hugodown/content/post/plainmd

This was born of my general struggle trying to create a new plain markdown post instead of a .Rmd post.

i.e. not in the drop-down menu but directly visible as "Configuration" and "Deployment".

"Configuration" could even be called "setup" (to me "Configuration" sounds a bit like "tweaks you might like" so less necessary to read than the article actually is :-) ).

While testing the new hugo_document format, I observe a very long rendering time for very simple document when the hugo server is not started.

I isolate the issue to be with the post processing part and specifically the active port checking.
I takes a whole minute of real time.

bench::system_time(hugodown:::port_active(1313L))
#> process    real 
#>  62.5ms   1.02m

This is obviously due to the try with socketConnection. There is a timeout that default to getOption("timeout") which is 60. see ?socketConnection

If I change the option to like 5 second, it is more quicker... 5 sec.

withr::with_options(list(timeout = 5), 
                    bench::system_time(hugodown:::port_active(1313L)))
#> process    real 
#> 78.12ms   5.07s

Maybe for a smoother user experience there could be smaller timeout set in hugodown to prevent this happening when the server is not started.

Let's not that when the hugo server is started, it takes less than 1s to check, so rendering Rmd file is as usual.

• Find academic syntax highlighting css
• Convert class names to chroma names

And document https://rmarkdown.rstudio.com/docs/reference/render_site.html#configuration

Store in appdirs cache directory using binaries available from https://github.com/gohugoio/hugo/releases

Retrieve version from config; if not set, use latest

Need to post process to:

1. Convert .md to .json ast using pandoc
2. Read json into R, then apply pkgdown highlighting to each code chunk
3. Convert back to .json

Note that goldmark does not preserve raw html (like pandoc does), so it would need to include a shortcode in the output, along the lines of https://anaulin.org/blog/hugo-raw-html-shortcode/

At the moment knitting my Rmd that has

authors:
  - Maëlle Salmon

gives

authors: Maëlle Salmon

I'd understand your closing this since I should make the theme robust to this change

For hugo sites, it's quite possible the site root does not contain a config.(toml|yaml), but rather a directory config/ with subfolders corresponding to environments.
See the hugo docs for examples.

I personally use this approach with only a config/_default folder purely because theme- and site configuration can become quite crammed if done in a single file, and I like the ability to divide "hugo stuff" into config/_default/config.toml and have theme-specific settings in config/_default/params.toml.

{blogdown} uses this same approach (determining site root by looking for config.toml), which is why I had to resort to a symlink.
That's not a big deal of course, but if the scope of this package is specifically to work with hugo, it might be worth it to find a neater solution.

The problem is that, while every hugo site root has to contain a config.* file or config folder, a themes directory and a contents directory — all these directory names can be configured arbitrarily (hugo options configDir, themesDir, contentDir).

The more I think about it, the more feasible it seems to just accept the minor caveat and expect a config.(toml|yaml), but I at least wanted to throw the idea out there.

Not sure if it's really useful but I am overwhelmed by all the stuff that's created by the function and was wondering whether there's a way to build the website that starts from having less things and adding folders (rather than editing and deleting). I guess I am wondering how @apreshill creates all her academic websites. 😉

From RStudio New Project menu, when distill is installed, one can select distill website / blog as a possible project. Would that be possible with hugodown? blogdown also supports that.

I found too many repetitive development ，for example:
do_it()
do.it()
itDo()
doIt()
just do it, how to choose?
Maybe we just need one, unified syntax, unified framework, integrated functionality.

Would there be scope to help transition from blogdown to hugodown, à la roxygen2md::roxygen2md()?

• Get active post from rstudioapi
• Resize thumb-sq.jpg to 300x300 (warn if not square)
• Resize thumb-wd.jpg to 200 high and warn if <1000 wide

Each blog post is basically like it's own project, so it makes sense for links to be relative to the Rmd, not the blog root.

Need to make sure this works both interactively, and from rmd_build().

Using hugodown::use_post(), the title in the post created is always blank (title: ""). This is confusing at first if you don't understand posts and slugs. For example, you can knit the post, but if you look at the rendered site's post listing page, you won't be able to click on the post to see it:

If you understand how Hugo works and that the actual link is post/no-title/ you can of course see the rendered post, but this is likely to be confusing for beginners. Would it be possible to either keep or enter a title into use_post()?

I am guessing this is the bit that overwrites the Hugo-ified title from the theme's archetype:

• blogdown New Post Addin is really nice when your theme is compatible (e.g. uses authors, not author)

• ymlthis also has an addin.

Differences with new_post()

• ymlthis and blogdown use whoami for the full name. usethis full name could still be prioritary but then whoami is a good guess and doesn't require configuration.

• blogdown addin loads existing tags and one can create new tags.

• blogdown addin lets you choose from several archetypes (e.g. if you have one for Rmd and one for md)

• having an user-friendly interface :-)

I am currently experimenting to see if I can easily switch from blogdown + .Rmarkdown to hugodown, and so far the first "issue" I have found is the chunk output.

I have prepared an example hugo blog repo using the same theme I'm using for my blog without any CSS / layout modifications. It's auto-deployed to netlify at https://hugodown-testing.netlify.app/

I have started two blog posts, one using hugo+goldmark, and one using hugodown:

• Plain Markdown post: https://hugodown-testing.netlify.app/plain-markdown/
• Rmd post: https://hugodown-testing.netlify.app/hugodown-rmarkdown/

Code output

I am assuming that the output of hugodown_document is intended to be as close to that of hugo/goldmark as possible, but where in the plain markdown / goldmark post, a code chunk looks like this:

where code is contained in two nested <div>s:

…hugodown however produces this output:

where the entire chunk is wrapped in <pre class="chroma">.

This leads to issues regarding the styling (margins, border-radius, probably why the colors differ?) in this particular theme, but I appreciate that this might not be a problem at all when using different themes (or using extra CSS).

I hope it's possible to adjust this without having to account for site-specific goldmark settings (like line numbers and tabular display in my case).
I would still like a solution where hugodown outputs code to a hugo highlight shortcode, but I assume that's not possible when downlit does the auto-linking / highlighting (which is very cool, I just tend to want to over-customize, and shortcodes give me a lot of flexibility across md + Rmd).

Plot output

Related to this are code chunks with plot output (live example):

Here the output figure is still contained in the above <pre>, causing the "code background color" — I assume this is not by design for some auto-linking/downlit-reason? If so, is there a way I can avoid this behavior?

you can also add a knit: entry to the metadata to override what happens when the user presses the knit button. If you emit a string with this format to stdout from whatever is called then that is what RStudio will preview: https://github.com/rstudio/rmarkdown/blob/7f51e232c98b2f7db40b40cd593385fe76b3189b/R/render.R#L948

i.e. in to public/

Using xxhash64 for speed

Currently with create_site_academic() the function overwrites the default post archetype with an index.Rmd file in: themes/academic/archetypes/post/. But, if a user updates their Hugo theme (which is recommended periodically), this archetype will be overwritten. Would you consider instead writing to archetypes/post/ in the project root? That would be more robust, and encourage good practices w/r/t updating themes when running into errors (just like we encourage folks to update their R packages).

Either through blogdown hack or via goldmark-mathjax

A bit vague since I don't fully follow how Rmd &pandoc handle citations.

With hugodown would there be a less hacky way to use refs from a .bib file than what I show in https://ropensci.org/technotes/2020/05/07/rmd-citations/ ? Ideally something that'd just work with the user referencing a .bib file in the YAML and refs with [@key] as they do in other R Markdown format. Having the citations as footnotes is I think ok.

That's the only missing part in the README, if I compare it to https://bookdown.org/yihui/blogdown/output-format.html

Specifically for the purpose of building publc/ hugo (i.e. would somewhat supply render_to_disk argument of server_start(). Should optionally write .nojekyll file for GitHub.

Could md_document gain an argument to not apply downlit ?

There was previously an option with hugo_document to switch on downlit

However it looks like that option has been removed now in md_document.

While I think that downlit is awesome, and I love the idea, at the moment I don't want to generate links to functions, as it seems to change the colours I get. Here's an example of what I meant:

Compare using downlit (from md_document) in this post

To not downlit (from hugo_document) in this post

I think that this issue with syntax highlight maybe has to do with downlit being used?

I have tried to follow the config guidelines as close as I could, but perhaps I've missed something in my blog set.

Might be too niche. I was thinking that some users might want to use a site-wide CSL, and even a site-wide bibliography (it was asked in the issue tracker of distill).

It's easy to get and I wonder whether it should be documented, maybe in an article about bibliographies.

• save the CSL and/or bib at the root for instance.
• in the archetype (since there's no site config for hugodown, just individual Rmds), add

bibliography: ../../../refs.bib
suppress-bibliography: true
csl: ../../../chicago-fullnote-bibliography.csl

I've just tested it.

Maybe hugo_start() and hugo_stop()? (And hugo_process())

Need to check config to ensure that it's ignoring the intermediate knitr files.

And then remove from template

Examples:

• https://github.com/jemus42/hugodown-testing/blob/master/public/hugodown-rmarkdown/index.html#L179
• https://github.com/jemus42/hugodown-testing/blob/master/public/hugodown-rmarkdown/index.html#L286

I assume the issue is that " and ' are replaced with " etc., where the page shows {{< pkg “hugodown” >}}.

I hope it's possible to work around this without having to resort to solutions like blogdown::shortcode(), which inserts preserving comments <!--html_preserve--> that do not work well with shortcodes that return inline-output (like a <span>), see the first example here https://github.com/jemus42/hugodown-testing/blob/master/public/hugodown-rmarkdown/index.html#L274-L279 which is displayed with additional linebreaks like here.

Blogdown's .Rmarkdown format renders markdown which preserves shortcodes, see for example here: https://hugodown-testing.netlify.app/blogdown-rmarkdown/#shortcodes (source HTML here, source .Rmarkdown here).

If the solution is a regex to detect/preserve shortcodes (I have not investigated what blogdown does there), please note that there are two kinds of shortcodes that may appear in the post source:

Shortcodes returning markdown: {{% mdshortcode %}}
Shortcodes returning HTML: {{< htmlshortcode >}}

Hi-

Using create_site_academic(), a few HTML widgets don't work out of the box:

• plotly (I'm unable to debug this, it isn't just a jquery clash)

• highcharter (this works if I add a page parameter to disable Academic's jquery version, but then for some reason the post title is partially hidden by the upper navbar 🤷‍♀️ )

• DT::datatable (this only works if I add a page parameter to disable Academic's jquery version; does not appear to affect CSS)

• reactable does work, even without any page parameter.

I'll test out a few more, but wanted to start an issue to track this.

https://bookdown.org/yihui/blogdown/output-format.html

• Run R code - yes
• Bibliography - #22
• Task list - yes
• MathJax - yes
• HTML widgets - yes

New:

• Runs R code automatically - no
• Cross-links - no

• Required components in hugo config (extracted from readme)
• Optional components in _hugodown.yaml

From @jjallaire

(1) Inherit from bookdown::html_document2()

(2) Call the helper function I asked Yihui to put in so I could support cross-references in distill

(3) Look at the code of that function and just do it yourself (that might be the best bet although I haven't actually looked at the code recently so don't recall how trivial or non-trivial it is)

See latest template at https://raw.githubusercontent.com/apreshill/tidyverse.org/add-archetypes/archetypes/blog/index.md

• The screenshots are missing from the vignette.

• Could the template feature different settings for previews and production, e.g. only build future posts in a preview? And/or could the docs explain that? "Common useful variations of the Netlify config".

• Could the docs (of the Netlify function, of the vignette) explicitly say what "--baseURL $DEPLOY_PRIME_URL" does? (as Details?) "This option ensures relative links to other pages of your site, e.g. See [my recent post](/post/recent-post), will be rendered by Hugo as links to your site as built in the preview (https://deploy-preview-692--blabla.netlify.app/post/recent-post), not your site as deployed in production (not https://hugodown.org/post/recent-post), which is useful when you change and check something site-wide such as stylesheets".

• And shouldn't this option above only be used for PRs?

Hello, is there a hugodown addin for RStudio available? Similar to blogdown?

Will hugodown have functions to install a theme from GitHub? Or is it mainly focused on existing Hugo/blogdown sites? If intended as a full Hugo site tool, I appreciated this feature in blogdown:
rstudio/blogdown#391

When I use knitr::kable() in a hugodown post, in the index.md I get a pandoc-formatted table, not a markdown-formatted table. I'm not sure why. :-)

I looked into how kable() defines its default format https://github.com/yihui/knitr/blob/683887b3169104592f3dbabb457e41aaee2af71c/R/table.R#L91-L104, the only switch seems to be a global option.

I see there's

See https://github.com/jemus42/hugodown-testing/blob/master/public/hugodown-rmarkdown/index.html#L221

<p><img src="plots/a-plot-1.png" width="0.95\linewidth" style="display: block; margin: auto;" /></p>

This results in the plot not being shown on the page, see here: https://hugodown-testing.netlify.app/hugodown-rmarkdown/#plots

When using e.g. Chrome's developer tools to remove the width attribute or correct it to width="95%", the plot appears.

I assume this is a result of the fix for #35 (re: #35 (comment))?

Noticing background colors around figure output:

I suspect it may have to do with the CSS Chroma additions? They go away when I remove the following CSS background colors:

pre {
	margin: 0 0 1rem 0;
	/* background-color: #f8f8f8; */
	border-color: #f8f8f8;
	font-size: 0.7rem;
	border-radius: 4px;
}
pre, code {
	font-family: "Roboto Mono", monospace;
	color: #c7254e;
	/* background-color: #f9f2f4; */
}

Also noticing that the figure resolution with hugodown rendering is not good. A fresh Academic site via blogdown shows much crisper figures (and no background color):

Document format:

• hugo_document() -> md_document()

Hugo functions:

• hugo_install() -> hugo_install()
• server_browse() -> hugo_browse()
• server_start() -> hugo_start()
• server_stop() -> hugo_stop()

File creation:

• post_create() -> use_post()
• tidy_post_create() -> use_tidy_post()
• tidy_thumbnails() -> use_tidy_thumbnails()

Misc:

• site_outdated() -> ???
• tidy_show_meta() -> ???

When I use languages other than R, the input sometimes appears as NA, although the output is unaffected. I've been able to replicate this with python, bash and scala.

In terms of a reproducible example, I've created a new hugodown site using the latest version of hugodown, and the function create_site_academic(). I created an R Markdown file with code chunks from these languages. I then knitted the markdown file which shows the NA inputs.

I'm happy to give this issue a go and try to find the cause as best I can. Thus far I've tried using another machine (Windows, without the bash chunk), and disabling link_inline. I think a hint here is that in the Python code chunk, print("This is a python chunk") isn't converted to NA. I suspect this is because that line is also valid R code.

:smile_cat: in the Rmd becomes :smile\_cat: in the md 😿