What is hard about blogdown? 🤯

General
1

Hello,

I'm teaching the "tada!-verse" in 2 weeks: blogdown + xaringan. So I'm wondering: what was hard about blogdown when you first started? One thing I have noticed is grasping how Hugo is designed to work by overriding rather than editing files- I think understanding the underlying file structure at first is hard. I also really struggled with integrating with Git, but I think that was my own git-comfort-level rather than blogdown. Other thoughts? I'll share my teaching materials with attribution at the end :woman_mechanic:

My students thank you!
Alison

10 Likes
2

Hi Alison,

I found it relatively easy to get a basic website going (thanks in no small part to your excellent tutorial on the subject), but have found making any changes to the default theme extremely hard. I'm still unclear, for example, how to change the default font - there is a note in the default blue.css, for example, to 'update link @ themes/hugo-academic/layouts/partials', which I am confused by. Also, I've found where/how to change some aspects of the colour scheme, but not others (I've been able to change the default colour for most of the text, but for some reason not the text that's formatted as code). This could be down in part to my fairly minimal css knowledge. So if your teaching material includes some tips along those lines, that would be much appreciated!

Now you mention it, I'm not sure I fullying understand overriding rather than editing. I'm also confused by the file structure. For example, there's a 'static' folder at the root level, then another 'static' folder under 'themes/hugo-academic/static', so I'm not clear on knowing what to edit/where to save overwrites. Really looking forward to seeing your teaching materials on this - I'm sure they'll be a great resource for the whole community (not just your students!) :hugs:

Ella

4 Likes
3

100% agree with this one, in the same line, also finding out that those file can be overridden in multiple places, and that there is a hierarchy that Hugo follows is a good thing to learn as early as possible

Also, the TOML file contents is a bit overwhelming if a new developer starts with an example that has a bunch of stuff in it.

4 Likes
4

Thank you, @EllaKaye! These are excellent and make total sense :star_struck:

5

Ah yes, thank you @edgararuiz! And if you are new to R Markdown, you just learned about YAML, so what the heck is TOML? Who is Tom and why does he need his own markup language?? :joy: And I totally agree about hierarchy- I remember thinking I should just delete all the empty folders :scream:

4 Likes
6

Hi I'm Tom, but I STILL don't know much about TOML!

  • A painpoint for me starting out was what to do with data? Cache it? Cloud it? Upload it?

  • Limited info on what to do AFTER you build the site, getting a website spun up locally is a huge win and is made relatively easy with blogdown material, but how to go about customizing your theme, adding various things to each portion (eg creating, knitting, and uploading posts vs projects vs presentations). All the stuff about actually RUNNING your blog in blogdown vs BUILDING your blog. I built prob 6-10 versions that worked fantastically on my local version, but didn't work well when I uploaded to netlify/github.

  • Probably more of a "I Need to Learn Git Better" more than anything else, but working with blogdown across multiple computers and writing posts away from my "blogging" desktop has been a pain. Yes I'm using Git and cloned to my laptop, but it doesn't play nice. :man_shrugging:

My blog is working now, but man that was a rough couple days getting through my customization and getting it fully setup so that I was happy with what I was putting out there (and not crashing the whole thing) :joy:.

TL:DR --- lots of great info about building a website (thanks to you!) but could be a lot more about the nuts and bolts of keeping it running and "happy".

Thanks for taking the time to gather this info! Good luck with your class!

2 Likes
7

If you keep everything standard, it's all fairly simple. If you customize anything, though, there are a lot of weeds, into which you can wade as far as you like (or reverse course).

Some difficulties for me seem to be idiosyncrasies of my theme (Future Imperfect), e.g. they type in the YAML has to be set to post to show up. Without that, Hugo doesn't complain, but the post doesn't show up.

More of my difficulties were products of not knowing where to stick things in the file structure, e.g. a favicon (getting mine to show up took hours), static (not generated by R code) images for posts, markdown docs for permanent pages in the site, etc. Compounding the issue is figuring out both where files will end up after Hugo runs and what path to put when referencing them, as there is some undocumented magic in places, e.g. featuredpath: "date" for featured images for posts.

In all cases the way I figured out most of the solutions was emulating the theme examples. When that didn't work, I went more for the shotgun "try everything and see what happens" approach, which usually gets me there, if not very efficiently.

Lastly, I've occasionally had issues with the "Serve site" add-in. Mostly, it's just hard to see if it's still running or active, as it usually doesn't print anything when it's working. A couple of my posts (e.g. one on Bayesian regression) took a while to compile, so occasionally my session would just lock up for a few minutes while it ran. I tried to ease the situation with caching, but that was mostly counterproductive. I suspect most people won't do such silly things in blog posts, though, so this may be a fairly unique difficulty.

Elsewhere in the "tada!-verse" (I love it), I'd recommend the under-loved flexdashboard to people getting started in RMarkdown. It certainly can't do as much as blogdown, but it can make a variety of static sites beyond the basic HTML report format. In my experience, its simplicity makes it much harder to screw up. It's a nice segue to Shiny, too, if people are so inclined.

1 Like
8

Hi there, thanks for the info! I totally agree on 1 and 3 :slight_smile: Wondering about 2 though. I haven't run into problems with my site working locally but not rendering properly. I HAVE had problems serving locally when I do silly things like accidentally knit a post. Can you elaborate? Thanks!

9

Yes you bring up lots of good points- like even just applying a vocabulary to things rendered by R versus "static" files versus things rendered by Hugo (like md docs). I love the flex dashboards too- I still wish there was a way to embed one into a larger R markdown site!

2 Likes
10

Regarding 2 - I guess the vast majority of the self-help guides I have personally run across have a lot of info for initial setup but less info or examples beyond the initial setup. Your personal post was definitely one of the most helpful!

I'm not quite sure if there was something I was messing up and just never knew (it is working great now), but I would have sites that spun up great locally and had content I wanted but when pushed to GitHub they would not deploy on Netflify. Could have been a GitHub issue (and likely on my end)!

1 Like
11

Gotcha, and I see you are using the academic theme like I am, which has lots of nice bells and whistles that are great but don't necessarily generalize to all themes.

I took a peek at your site to look for ideas :thinking: Like this project (https://thomasmock.netlify.com/project/customer-churn/) is so cool, but the ggplot graphics aren't rendering b/c (I think) it was a markdown document from what I can see in github. I don't see a build.R script, so wondering if this kind of solution might have fixed (some) of your pain points? https://blogdown-demo.rbind.io/2017/09/06/adding-r-markdown-documents-of-other-output-formats/

If it is problems like that, what you ran into would reinforce @alistaire's point- the vocabulary is lacking to even be able to know what to google!

1 Like
12

Yes! Someone from the community pointed out that I saved it as a markdown and not R Markdown.

I MADE SO MANY GRAPHS :joy: none of which show up. :stuck_out_tongue:

I appreciate the link, I'll take a look at it!

I think you hit it on the head, I ended up having issues that were more likely related to hugo than to blogdown itself, making the vocabulary awkward for me to search for.

1 Like
13

Yea even in that blog post I kept thinking "How do I talk about this?" We kept calling it R Markdown of arbitrary formats, which is totally opaque, or "static files" which also is sort of misleading. It is hard to think of a term for this kind of thing, b/c we document it in the blogdown book, but when you read it it isn't quite clear still when you would run into this problem. If you think of a better way to talk about it (or similar issues) I'm all :ear:

1 Like
14

I'll think on it, and I really appreciate your blogpost! It was great, and I should have read it a few times BEFORE starting my blogdown instead of during!

:stuck_out_tongue_winking_eye:

1 Like
15

If I get what you're saying, maybe one way to talk about where a file is headed is by referencing the primary tool that renders the document, e.g.

  • RMarkdown is R-dynamic (more specifically, blogdown- and rmarkdown-the-package-dynamic), turning (mostly) into raw Markdown
  • raw Markdown, which is Hugo-dynamic (or pandoc-dynamic)
  • plots are R-dynamic, whereas other images are static (they're already rendered)
  • themes, templates, TOML config files, etc. are Hugo-dynamic
  • htmlwidgets are R-dynamic when compiled and then JavaScript-dynamic in the browser
  • Shiny is R-dynamic on a server

...or something like that. Where the rendering happens sometimes matters too, e.g. for Shiny. A nice diagram could be drawn here.

1 Like
16

Hi @apreshill, between your co-authored book and your blog post, makingmy website it was pretty simple (thanks for the great resources). The most difficult thing for me to figure out getting the color scheme to be correct across the entire site--specifically the buttons. I ended up having success when I modified my default.toml in my data/themes directory.

There is one other change that I haven't figured out (I'm not sure its possible), which is ensuring that the website meets ADA web accessibility standards (I'm using the WAVE tool to check on this). For some, things (such as not skipping header levels) the changes seem pretty simple). For others, I haven't quite figured it out yet, such as adding text descriptions to the icon.

2 Likes
17

In fairness, I'm not known for short-form materials :sleeping:

18

yes this is perfect- sort of like a life cycle for the docs that go into your website. I'll play with this and report back!

1 Like
19

I actually think this question encapsulates a lot of what's tricky about blogdown as you've described it!

Form and function can seem intertwined, and the role of the theme itself isn't always obvious (Hugo design), etc.

2 Likes
20

It's also interesting that a lot of the online tutorial help seems to focus on installation rather than content creation. Apart from blog posts, content creation tends to be covered by "look at the examples and modify them". That had actually been working for me up until I touched the project examples and then everything seemed to break with no error messages.

There is a little online advice on deleting content which says "delete the content from the content folder". That's what seemed to trigger the problem.

It's not clear to me what a reprex would even be for this: copies of the entire website before and after it stops working?

1 Like