How to link custom stylesheet from org-mode?

Hugo Version: 0.46
Format: org-mode via ox-hugo
theme: hugo-dusk

I would like to be able to add custom styles to my posts. I am happy to do this via plain CSS style sheet or SASS / SCSS.

What have I tried
I created a simple css file and saved it to the /static directory. I tried to use #+HTML_HEAD and #+HTML_HEAD_EXTRA to add the reference link, but neither exported the link so they must not be supported. I have spent a lot of time reading through hugo documentation as well as org-mode documentation, but I can’t seem to find a solution. I have also looked through ox-org.el to see if I could find a solution there. I noticed that ox-org does have a #+HUGO_RESOURCES property which adds resources to front matter resources. Front matter resources are for files in the content directory though and my css is in the static directory.

Any ideas would be appreciated.

The default Org mode HTML exporter generates whole HTML files.

ox-hugo exports only the Markdown content.

So you need to tweak the CSS in the layouts/themes section of your Hugo project.

The separation is clear:

  • The content/ directory of Hugo can contain only content. Stuff in there cannot go into your page <head> tag. You can of course put in inline CSS in there if you like in <style> tags. But that’s probably what you don’t want.

    ox-hugo touches only this dir (and static/ if needed).

  • The layouts/ or themes/ dirs contain the non-content, the layout/structure of your HTML pages, etc.

    ox-hugo does not touch your site layout.

Those are different “resources”… used to set this resources meta-data/front-matter.

This is a simple bare bones Hugo site. You can find its source here. See how it gets its layout, CSS, JS, etc. from its hugo-bare-min-theme theme.

You might need to do general reading to understand the Hugo directory structure.

Thank you kaushalmodi,

I was reading the documentation on content-management and static files

By default, the static/ directory in the site project is used for all static files (e.g. stylesheets, JavaScript, images).

The documentation covering the hugo directory structure also mentions that the static file directory can be used for CSS.


Stores all the static content: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the static folder is for verifying site ownership on Google Search Console, where you want Hugo to copy over a complete HTML file without modifying its content.

So that tells me that I can put style sheets in the static directory. I suppose I can put anything I want in the static directory, but it suggests that I can put a style sheet in the static directory for some useful purpose. So if it were possible to add to the header a link to a style sheet contained in the static directory then I would be able to add my own custom styles without modifying the third party theme that I am using. Essentially I want to add a link like this:

<link rel="stylesheet" href="//localhost:1313/my-custom-styles.css">

You are telling me that it is not possible to do that. Does that mean that when the documentation suggests putting CSS in the static directory it is really directed towards those people creating themes? Or is there a way that I can add a link to the document header to reference my own statics css.

On a side note, if I have a specific question about ox-org where should I go to ask it? Should I just post it as an issue in github or ask it on this forum? or somewhere else?

Thank you for your time.

Touché. I should clarify that ox-hugo touches the static/ dir only to copy attachments (images, pdfs, etc.).

Enabling copying/overwriting of CSS would fall too much out of ox-hugo scope.

ox-hugo is only for content management… which includes the images associated with your site content (markdown).

Hope that makes the scope of ox-hugo clearer.

Correct. But they are useless unless you update your layout files to use those CSS files. So you anyways need to edit the layout files manually. So you might as well copy the CSS files manually.

Of course it is possible! But you need to do that in your layout files. In my bare min theme, I inline the CSS, but you can put in that link tag if you like.

Questions for ox-org would go to Org mailing list:

That has nothing to do with ox-hugo or Hugo :slight_smile:

You’re welcome.

1 Like

Sorry, I meant ox-hugo, not ox-org.

Thank you for your last post. That made everything very clear. I marked it as the solution.


Then you can open an issue on