gohugoio / hugobasicexample Goto Github PK

Update the site config to include:

pygmentsCodefences = true
pygmentsUseClasses = true

And specify the language used for fenced code blocks. Doing so will better help user expectation meet reality for sites which use the basic example but end up looking different when they're installed.

If this project is meant to test a theme before submitting it to Hugo themes repo, it would also make sense to provide criteria, as to the test has passed or not. Examples:

• Quite a few "test cases" end up in blocking RAW HTML code. What am I supposed to make of that? That hardly means my theme is "broken", as RAW HTML handling is defined in project configuration.

• My theme relies on pygmentsUseClasses = true et al. The test project doesn't, and so inline styling is applied. As a result, the appearance is a bit ugly. Is it acceptable to instruct the user to configure the project accordingly?

Given that theme authors are now responsible for providing their own sample content, I suggest we archive this repository.

A little reminder re. the discussions about Goldmark.

This example should run fine with:

• Unsafe = false
• Inline shortcodes turned off

This project is supposed to be basic.

According to @onedrawingperday in #57 (comment) Goldmark is now able to render the Math Typesetting example, but apparently it shares one same problem with Blackfriday where inline math will be rendered as a block.

Digging the forums, the previous recommendation was simply "use mmark instead" (see: https://discourse.gohugo.io/t/katex-inline-math-in-md-vs-mmark/19141/2).

Am I missing something?

Similar to #34 but this time the content will be product placeholders.

Tangentially related to #7 there are now some errata in the template primer, namely:

• Example 1 attempts to pipe to if (something I would like to use personally for more declarative one-liners, e.g. {{ eq $value "true" | if }}{{ $name }}{{ end }}) resulting in unexpected <if> in command error.

If I spot any others I'll loop back and drop 'em here.

Create a Portfolio Page Bundle that references its own content and sample images.

Just wanted to mention that I recently re-installed windows 10, downloaded go, and tried the hugo install from github on the gohugo.io install page instructions and received the following error message:

# github.com/bep/gowebp/internal/libwebp
cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in %PATH%
# github.com/bep/golibsass/internal/libsass
cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in %PATH%

so perhaps another comment might be usefully added to the installation instructions. I will attempt a solution and post back.

I'm new to Hugo, so if I'm just doing something stupid please let me know!

I checked out the hugoBasicExample via the instructions here: https://github.com/gohugoio/hugoBasicExample. On step 3, I checked out all the themes according to those instructions. I then launch a server via
hugo server -t slate

I then point my browser at http://localhost:1313 and all I see is this:

I've tried a couple other themes as well, with mixed results. Some show almost no content, other ones seem to have content (I can see sections for Markdown Syntax Guide, Rich Content, and Placeholder Text on some). Is this an issue with the content in the example itself, or with how individual themes deal with that content? As mentioned in my opening line, I'm new to Hugo so I'm trying to come up to speed on how things are "supposed" to work. My original assumption going in was that the layout of your content files should work with any theme, but I'm now thinking that assumption isn't valid and that you need to organize your content specific to the theme you plan to use?

Here's the output I get on the command line when running with the Slate theme:

C:\Users\sean.murphy\Documents\Markdown\hugoBasicExample>hugo server -t slate
Start building sites …
hugo v0.89.4-AB01BA6E+extended windows/amd64 BuildDate=2021-11-17T08:24:09Z VendorInfo=gohugoio
WARN 2021/12/01 11:48:04 The "twitter_simple" shortcode will soon require two named parameters: user and id. See "C:\Users\sean.murphy\Documents\Markdown\hugoBasicExample\content\post\rich-content.md:26:1"

                   | EN
-------------------+-----
  Pages            | 26
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  9
  Processed images |  0
  Aliases          |  9
  Sitemaps         |  1
  Cleaned          |  0

Built in 102 ms
Watching for changes in C:\Users\sean.murphy\Documents\Markdown\hugoBasicExample\{content,layouts,static,themes}
Watching for config changes in C:\Users\sean.murphy\Documents\Markdown\hugoBasicExample\config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Thanks in advance!

Steps to reproduce:

1. Open taxonomy list page in theme demo from themes.gohugo.io site, for example Binario markdown tag page.
   Other examples: 1, 2, 3, 4.

Screenshot:

It looks like due to the symlinks in the posts folder.

I've tested this on my Mac with hugoBasicExample:

• v0.57.2/extended: duplicated pages
• v0.56.3: no duplicated pages

I don't know how Hugo works with symlinks, but it looks like something changed.

The build for my theme Tale when using the Hugo Basic Example site is currently failing with the following error:

Error: Error building site: "/home/travis/build/EmielH/tale-hugo/hugoBasicExample/content/post/math-typesetting.mmark:28:5": failed to extract shortcode: template for shortcode "math" not found

When building locally, I get different errors (although the site does work when using hugo serve).

2019/04/09 20:52:32 mmark: failed: ` if or .Params.math .Site.Params.math ': open  if or .Params.math .Site.Params.math : The system cannot find the file specified.
2019/04/09 20:52:32 mmark: failed: ` partial "math.html" . ': open  partial "math.html" . : The filename, directory name, or volume label syntax is incorrect.
2019/04/09 20:52:32 mmark: failed: ` end ': open  end : The system cannot find the file specified.
2019/04/09 20:52:32 mmark: failed: ` if or .Params.math .Site.Params.math ': open  if or .Params.math .Site.Params.math : The system cannot find the file specified.
2019/04/09 20:52:32 mmark: failed: ` partial "math.html" . ': open  partial "math.html" . : The filename, directory name, or volume label syntax is incorrect.
2019/04/09 20:52:32 mmark: failed: ` end ': open  end : The system cannot find the file specified.

Tale doesn't have its own exampleSite and also doesn't include this shortcode. This repository also doesn't seem to contain this shortcode.

Is there anything I need to do to make the build work again, or is this an error in the Hugo Basic Example?

I would like to propose the addition of a second language to the hugoBasicExample. I am glad to contribute with Greek translations.

This will help in determining which themes support multilingual functionalities. Hopefully this wouldn't cause any compatibility issues with themes that do not.

https://github.com/kazi-sifat-plus9a/blog.github.io.git
https://gitlab.com/kazi-sifat-plus9a/blog.gitlab.io

**gitlab pipelines error **

`Checking out e5c64e79 as master...

Updating/initializing submodules recursively with git depth set to 50...
Executing "step_script" stage of the job script
Using docker image sha256:af2fb5a209c9cb1a4febee5471e6e8383020f94302bf51d1d6413371cee6ce12 for registry.gitlab.com/pages/hugo:latest with digest registry.gitlab.com/pages/hugo@sha256:ec905fcdaf3b882cb3fc4b19b55b7151a12d28519ceaa6c783a079a6db983979 ...
$ hugo server
Error: module "hugo-theme-stack" not found; either add it as a Hugo Module or store it in "/builds/kazi-sifat-plus9a/Blog/themes".: module does not exist
Cleaning up project directory and file based variables
ERROR: Job failed: exit code 255

`

There a few themes that use a series taxonomy, so I will add this taxonomy in the front matter of the content files of this repo to accommodate these themes' demos.

ref: gohugoio/hugoThemes#560

stou@stou-mba:HugoBasicExample$ hugo server -w -t stou-dk-theme
0 draft content
0 future content
3 pages created
6 tags created
2 categories created
in 57 ms
Watching for changes in /Users/stou/code/hugo/HugoBasicExample/content
ERROR: 2014/11/19 Walker: lstat /Users/stou/code/hugo/HugoBasicExample/layouts: no such file or directory
Serving pages from /Users/stou/code/hugo/HugoBasicExample/public
Web Server is available at http://localhost:1313/
Press ctrl+c to stop
^C[2]stou@stou-mba:HugoBasicExample$ hugo version -v
INFO: 2014/11/19 Using config file: /Users/stou/code/hugo/HugoBasicExample/config.toml
Hugo Static Site Generator v0.13-DEV buildDate: 2014-11-19T23:13:09+07:00
stou@stou-mba:HugoBasicExample$

I tried multiple times and everything works in local but when I push on github pages everything is broken

here is my baseURL
baseURL: "https://smkplus.github.io/MyRepo.github.io"

Relevant issue: gohugoio/hugoThemes#556 (comment)

The menu configuration is currently in the front matter of the content files in this repository.

Since gohugoio/hugoThemes#547 made the contentDir of this repo mandatory for theme demos on the Hugo website the menu settings need to move in this repo's config.toml

So that:

• Themes that use this repo for their demo will continue to have the same number of menu items.

• Themes with their own exampleSite will still have custom menu links through the exampleSite/config.toml.

It just needs:

mkdir ./static
touch ./static/.gitignore
git commit ./static/.gitignore

better might be to get hugo to create the missing dir?

Summary

This issue is being created with the intent for myself ( @danielfdickinson ) to create a PR to fix it, shortly.

The problem in a nutshell is that

Discussion

During a thread on the Hugo forum called .Site.Author Usage?, it was pointed out that the docs say .Site.Author expects config.toml to have an author map .

This repo has author = "Steve Francia"

which is a 'flat' (scalar) variable, which as far .Site.Author is concerned is an empty map (as verified with a testing).

In addition, apparently the internal RSS template expects a map which has 'name' and 'email' as keys

E.g.

[author]
name = "Your Name"
email = "[email protected]"

Further, .Site.Author can handle having an 'authors' key which is a map with multiple subkeys (site-dependent values).

This is potentially useful for consistency in theme design for handling authorship.

Conclusion

The expected definition of author seems to have changed from scalar to map, and this repo should reflect that. (PR to be added later today).

The README of the repo should offer detailed instructions for theme authors.

It would be ideal if there were translated posts for the most common languages to properly showcase multilingual themes. Not to volunteer someone, but @VincentTam could probably do some quick translations of the posts to at least French and Chinese. Additionally, it would be ideal to have at least one post that does not have a translation so users can see how that would look on their site.

Whenever I commit a change to any of my themes, I have TravisCI run htmlproofer on a site generated using hugoBasicExample to check whether the generated HTML is still valid. As I commited a change today, htmlproofer found several broken internal links:

- public/post/goisforlovers/index.html
  *  internally linking to /content/front-matter, which does not exist (line 315)
     <a href="/content/front-matter">front matter</a>
  *  internally linking to /layout/functions, which does not exist (line 127)
     <a href="/layout/functions">Hugo template functions</a>
  *  internally linking to /layout/variables, which does not exist (line 110)
     <a href="/layout/variables">variables</a>
- public/post/migrate-from-jekyll/index.html
  *  internally linking to /doc/shortcodes/, which does not exist (line 108)
     <a href="/doc/shortcodes/">shortcodes</a>
  *  internally linking to /layout/templates/, which does not exist (line 102)
     <a href="/layout/templates/">Hugo’s template</a>
  *  internally linking to /overview/configuration/, which does not exist (line 76)
     <a href="/overview/configuration/">Hugo configuration documentation</a>
htmlproofer 3.10.2 | Error:  HTML-Proofer found 6 failures!

See this log from TravisCI.

I checked the source code of the basic example repo to find that the lines containing these links have not changed in a few years. I also checked the htmlproofer repo and it seems that there haven't been any changes pertaining to internal links there either.

Do you have a clue what might have triggered these errors all of a sudden? Have there been any other changes to hugoBasicExample that may have triggered these?

Thanks for your help!

As the refactoring continues I am looking into providing a few images for theme demos.

Currently this can be done in two ways:

1. Use https://picsum.photos/ and simply reference a random image via a parameter

2. Host a few placeholder images directly under /content/ in this repo.

In both cases images will be from Usplash since they provide images that are free (as in beer) to use and distribute without limits see their licence

So the question is which solution do you prefer: Put images in the repo or use the picsum service?

I think that the picsum service is simpler but as it happens with these services they have the risk of possible tracking and shutting down sometime in the future.

So I am in favor of selecting a few images and hosting them in the repo.

But I also want to hear your opinions before this is addressed.

cc: @digitalcraftsman @bep and anyone else.

This basic example uses outdated docs as demo content. It's also widely used by other themes and as default content for themes on the theme site.

It should be replaced with more neutral content, i.e. a page that explains the basics of Markdown to show how elements of the website like headers, paragraphs, images and tables look with a certain theme.

@rdwatters

The example content source code incorporated here is a snapshot (taken two years ago) borrowed from its canonical location in spf13/hugo.

As I'm aware, Hugo's showcase of themes (spf13/hugoThemes) is generated by a shell script resident in repository spf13/generateThemeSite. Repeatedly (and desirably), Hugo's theme showcase presents the same default content, each time utilizing a different theme.

If any theme lacks its own example content (in its own directory exampleSite/content), the example content from this repository supplements it in the showcase (as this shell script line reveals).

For a showcase to present content repeatedly is good in many ways. However, here, apparently—in practice—some setup detail has led many themes to:

• Re-borrow the example content from this repository; and
• Incorporate it in their own source code!

When we look at a particular theme in the showcase, it makes no visible difference whether the identical content is:

• Automatically copied (from this repository by the above shell script); or
• Already present in the theme's source code.

Arguably, the combination of borrowing and incorporating content into this repository, and then presenting it automatically in Hugo's theme showcase (rather than simply referring to it):

• Enables (or stimulates) certain themes to borrow and incorporate into their own repositories some of Hugo's documentation content; and
• Obscures that they do so.

In a repository, incorporating borrowed Hugo documentation source code IMO is a bad thing—when we consider Hugo's presumed overall goals of keeping its documentation (found anywhere in the wild) up to date (as far as possible) and improving it.

Since this repository—along with some of the themes—is providing obsolete content in the showcase, it seems likely that people sometimes will read it. For people to read obsolete documentation in general IMO is undesirable for them, and for us.

For example, when we look at hugo-cactus-theme in the showcase, we observe that the creating-a-new-theme.md document (in its example site) is outdated, compared with Hugo's current copy of the same document.

Incorporating copies of documentation source code into other repositories isn't something people naturally do. However, once a piece of documentation source code has escaped "into the wild" (i.e., is copied into other repositories, due to people being encouraged to do so), it's extremely difficult—naturally—to keep it up to date (in those copies).

This problem should be corrected IMO sooner rather than later, before the increasing number of Hugo themes further worsens the problem.

Perhaps this example content would be better as Lorem ipsum text? Or would it be better if the shell script automatically copied this example content from spf13/hugo each time it runs?

Which solution is preferable (or perhaps another)?

Presently, Hugo's user base seems large enough to benefit from such a change. And this repository IMO seems the best place to start.

Currently, nineteen (19) repositories (beyond this one) have incorporated some of the spf13/hugo documentation source code. The problematic theme sites are:

• appernetic: hugo-bootstrap-premium
• crakjie: hugo-base-theme
• devcows: hugo-universal-theme
• dgraph-io: hugo-dgraph-theme
• digitalcraftsman:
  • hugo-cactus-theme
  • hugo-hikari-theme
  • hugo-icarus-theme
  • hugo-minimalist-theme
  • hugo-steam-theme
  • hugo-strata-theme
  • hugo-type-theme
• djuelg: Shapez-Theme
• Eisenbarth: slender
• jbub: ghostwriter
• jpescador: hugo-future-imperfect
• lambdafu: hugo-finite
• syui:
  • hugo-theme-arch
  • hugo-theme-wave, in two (2) places: here and here
• yoshiharuyamashita: blackburn

Here are some references (for your enjoyment):

• Single-source information (Agile Modeling)
• Orthogonality & the DRY principle (Artima Developer)
• Don't repeat yourself (Wikipedia)
• Don't repeat yourself (Ward's Wiki)
• Once & only once (Ward's Wiki)

Provide a Headless Bundle for theme authors who need to have placeholder text in different sections of the homepage (meant for single page application themes).

To assist in theme selection for users of screen readers demo theme should include some hyperlinks as discovered here: https://git.habd.as/comfusion/after-dark/issues/3#issuecomment-7

When building the site, I get the following warning:

WARN 2022/03/03 09:12:53 The "twitter_simple" shortcode will soon require two named parameters: user and id. See "/path/to/hugoBasicExample/content/post/rich-content.md:26:1"

Steps to reproduce:

git clone https://github.com/gohugoio/hugoBasicExample.git
cd hugoBasicExample
git clone https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo
hugo -t beautifulhugo

The existing ID-only syntax in the twitter_simple shortcode seems to have been deprecated in favour of using user and id parameters, similarly to the tweet shortcode.

Should the archives.md page have a type of posts instead of section?
This doesn’t seem to populate the page in theme tests, or am I doing something wrong?
What is more, there’s no archives layout mentioned in the docs at all.

---
date: 2019-05-28
type: section
layout: "archives"
---

My blog on github pages http://akagi201.github.io you can try any post.
It will get like : http://localhost:1313/book/book-template/

sorry, my mistake

Installing all themes errors out when it reaches hugo-grapes because that submodule no longer exists.

Even if you do install all the themes, none of them seem to actually work - all Page Not Found with lots of this sort of thing in the console:

WARN found no layout file for "html" for layout "archives" for kind "page"

Cloned 'themes' per instructions to find almost a Gigabyte of folders and files. Might help to pare down selection in order to get a POC up faster. Also considerate to reduce options for users with slower connections.