Github issues that I have submitted and topics posed here have been closed immediately because they are deemed not a hugo issue. How is this determination made? Where can I find a raw hugo that does not depend on a theme, and that can be used to test primitive functions like the figure shortcode? It seems layouts must be populated, either locally or in a theme, before anything can be done. Is there a canonical way to do this that is theme-independent and could be used to determine whether or not there is a problem with hugo, rather than with a theme or with CSS? I have found examples where hugo sites are built without using a theme, but is there a canonical way to do this that will not break hugo shortcodes?
Not “canonical” by any means, but…
Thanks for the pointer. It appears that a good solution to my original question would be to
modify the ‘hugo new theme’ command to include a --canonical option (or a --test option)
that generates a minimal theme that can be used for testing hugo with no entanglement
with third-party themes. It should also provide a canonical way to include custom CSS.
This would permit stand-alone testing of Hugo, and solve the “not a hugo issue” problem.
Simply do not use a theme at all and write a basic template for a single page.
And perhaps: follow the advice people give you. What’s the point asking here if you’re not interested in the answers?
2 Likes
I should have mentioned that I did use Bryce Wray’s excellent introduction, sorry.
It helped me to drill down on issues that I have reported here and on github, regarding custom CSS and formatting. For example, I can refer to static/css/mystyle.css by adding to Bryce’s baseof.html head section: <link rel="stylesheet" href="css/mystyle.css">
But this style information only apples to content files, not shortcodes, and I am forced to explicity specify style information in shortcode files like this:
<h1 style="color:red;">This should be red text</h1>
Also, the styles defined in mystyle.css are not recognized in the hugo figure shortcode, for example class="center" has no effect.
Using <style> tags in a shortcode file is not very useful because this seems to apply the styles to ALL shortcodes.
On using hugo without a theme, since a theme is just a collection of templates and css files, this might more accurately be desribed as using hugo with a home-made partial theme, and this could be more error-prone than just using a third-party theme. For this reason it might be helpful to at least identify a canonical theme that is likely to work with all of the hugo shortcodes, for example, and that provides a canonical way to test custom css files. Something like this probably exists to do unit testing of the standarad hugo shortcodes.
This sentence makes no sense. Styles are applied to the generated HTML. All of it. Unless you do something to prevent that.
Several people have told you to look at the HTML in your browser’s developer tools. You apparently don’t want to do that. That’s your prerogative. But whatever you’re writing has nothing to do with Hugo. It’s not a question of theme vs. no theme, nor of shortcodes vs. content. It’s all about how you tell Hugo to generate the HTML.
EOT for me.
Let me try to summarize the CSS issues that I have observed, starting from Bryce’s introductory example. Modify his baseof.html as explained above to refer to the stylesheet static/css/mystyle.css. This style sheet formats classes .center and h1, where the first centers the element, and the second colors it green:
.center {
display: block;
margin-left: auto;
margin-right: auto;
width: 50%;
}
h1 {
color: green;
}
Next modify Bryce’s `layouts/_default/index.html’ to include:
<h1>This line is formatted using h1 in layouts/_default/index.html</h1>
This line is colored green as expected.
Now use the hugo figure shortcode in his file content/firstpost.md as follows:
{{< figure src="/images/foo.jpg" alt="Missing" class="center" >}}
The image is NOT centered as expected, so the stylesheet is not used. Probably it is
overridden. Indeed, it seems that all shortcodes have their styles overridden in
this way. To see this, define the shortcode layouts/shortcodes/myshortcode.html as
follows
<!--
<style>
h1 { color:blue; }
</style>
-->
<h1>This line is using h1 format in myshortcode </h1>
<h1 style="color:red;">This line is using explicit style color:red in myshortcode</h1>
Use this shortcode by placing it above the figure shortcode in firstpost.md
{{< myshortcode >}}
The color of the first line is black (not green), and the color of the second line is red.
If the <style> lines are uncommented, the first line is blue. Finally, if the CSS code
for .center is included in the <style> code block here, it applies to ALL shortcodes,
including the hugo figure shortcode, and it is centered!
This might help clear things up. Give it a try.
git clone --single-branch -b hugo-forum-topic-45971 https://github.com/jmooring/hugo-testing hugo-forum-topic-45971
cd hugo-forum-topic-45971
hugo server
2 Likes
Thanks! So the lesson seems to be to use assets/css/main.css as you do with .RelPermalink instead of hard-coding a reference to css/mystyle.css from static, because the latter is not resolved properly. The shortcode myshortcode works as expected with this configuration.
Just… no.
This URL is relative to the current page (incorrect): css/mystyle.css
This URL is relative to the server root (correct): /css/mystyle.css
1 Like
No. That’s not the lesson. assets is for files that are handled by “Hugo Pipes”: they are in some way transformed, like converting Sass to CSS.
static is for files that you can use as is. Like fonts, some images, some styles. In any case, your URL must refer correctly to them, as @jmooring pointed out.
The lesson is:
- either put your resources in
assetsif you are going to somehow modify them before including them in your site - or put them in
staticand refer to them with an absolute URL.
2 Likes
Thanks for the clarification. So the mistake that triggered this thread was not specifying the path to the CSS file relative to the server root, but much was learned along the way!
My feeling is that Hugo needs an overhaul of the docs to make it more inviting for beginners. Unfortunately, that would take a long time, and we don’t have any volunteers or the cash on hand to pay someone for their time, so I don’t see it happening anytime soon.
As an intermediate step though, I think the hugo new generator should be updated or have a new feature added that makes a very basic site for people to work with. If you want to jump into using a theme, the current generator is fine, but for people who want to learn how to do a basic setup, it’s not a very good starting point. Something like jmooring’s GitHub - jmooring/hugo-testing at hugo-forum-topic-45971 would be a better place to start in terms of showing new users the basic relationships between the parts.
2 Likes
With v0.118.0 and later the hugo new theme command creates a minimal, functional theme with sample content. To quickly create a test site:
hugo new site mysite
cd mysite/
hugo new theme mytheme
echo "theme = 'mytheme'" >> hugo.toml
hugo server
If you would prefer to create a test site without a theme:
hugo new theme mysite --themesDir .
cd mysite
hugo server
3 Likes
That’s a better start, but it’s still not quite functional enough for a beginner to Hugo. You still have to know how to hook up a few too many pieces before you can start hacking on the HTML.
There should be a simple command that creates a small site with content files for the homepage and one sample page, assets for an empty CSS file and JS file, and clear differentiation between the single.html and list.html, so you know which template you’re editing. It’s a tricky balance between giving just enough files to let people start hacking on it, and giving too much and imposing your opinions on them, but I think that the minimum layout should support a tutorial that reads like
Open your browser to http://localhost:1313. Now switch to your text editor and open
content/_index.md. Change “Hello, World!” to “Hello, [your name]”. Save the file and switch back to your browser. The page should automatically reload with your changes.
Once someone sees the browser autoreload work, it clicks the gear that makes everything else just a matter of trying things and seeing what happens, but you have to get them to that point first and preferably quickly!
I made an issue for this: Add command hugo new tutorial with a simple site skeleton for beginners. · Issue #11428 · gohugoio/hugo · GitHub
I have found that a good theme like hugo-book can be used out-of-the-box with little understanding of the internal structure of Hugo, but having this understanding surely helps. Thus it is important not to get lost in low-level details, and to keep in mind the leverage available with a good theme.
That said, as a new user, I find it useful to think in terms of “splices.” Usually the main page
content/_index.md contains Markdown, that is basically a collection of splices, and Hugo
shortcodes are also splices defined in template files under layouts/shortcodes. The core
template files baseof.html, main.html, list.html, and single.html define splices that are
used based on the type of content being rendered. Pages are bound together using
Go template code in these splices.
The new (as of 0.118) demo theme feature can be used to follow the order in which
templates are used dynamically by inserting print statements at the top of each template
file that shows the full path of the content file, template file, or partial. This will make it
clear when project level files override those provided by the theme. In the case of partials
where printing can be a problem use
{{ "<!-- hugo: using themes/mytheme/layouts/partials/foo.html -->" | safeHTML }}
Then use View page source in the browser.
Incidentally, this kind of splicing is sometimes used in the context of foreign language
interfaces. For example, HaskellR permits use of R inside Haskell by splicing R code
into Haskell. Something similar happens in Hugo using Go templates to splice
Markdown+Shortcode into HTML (templates and shortcodes are not defined in
the Markdown files to make things simpler for the site developer or author who
is not familiar with Go).
Use v0.118.0 or later.
Closed.
1 Like
This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.