r-lib / hugodown Goto Github PK
View Code? Open in Web Editor NEWMake websites with hugo and RMarkdown
Home Page: https://hugodown.r-lib.org
License: Other
Make websites with hugo and RMarkdown
Home Page: https://hugodown.r-lib.org
License: Other
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.
library(purrr)
md <- fs::dir_ls("content", recurse = TRUE, glob = "*.Rmarkdown")
yaml <- map(md, rmarkdown::yaml_front_matter)
unique(unlist(map(yaml, "tags")))
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://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.
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:
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()
?
thumb-sq.jpg
to 300x300 (warn if not square)thumb-wd.jpg
to 200 high and warn if <1000 wideEach 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:
Lines 129 to 133 in 6812ada
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:
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).
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.
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:
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
New:
_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)
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
Line 126 in 51d365b
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.