The initial postings on Hugo (https://flaviocopes.com/boring-stack/, https://gohugo.io/) make Hugo sound very easy to install and use. I would have been helped if they had mentioned that Hugo requires understanding and installing GitHub, even just for the Quickstart evaluation.
Apparently, running Hugo requires selecting a theme, which inserts various files in various Hugo directories, so GitHub is required for running Hugo.
Since I find using a command line and using GitHub to be awkward for my Windows web development, it would have saved me time if the requirements for Hugo had been stated up front. For me, not being a GitHub user, Hugo appears to be interesting but unusable.
If the directory containing the site’s config.toml is foo, then you create foo/themes.
Copy the extracted zip to foo/theme/ananke/ directory. Here things can go wrong if the directory nesting is not correct.
It’s just better to install Git for Windows and run the suggested git commands.
PS: GitHub is an online service to host git repos whereas git is a free and open source software available on all OSes.
GitHub happens to ship its Desktop software with git installation as part of it. If you are using Windows and not familiar with git at all, it’s best to install the GitHub for Windows. But don’t confuse GitHub with git
Extracting the zip file on Windows creates a top-level directory named gohugo-theme-ananke-master . You didn’t mention this. I’m assuming that the contents of gohugo-theme-ananke-master need to be moved up a directory, so they are in the “ananke” directory.
Now I’m lost. How do I run the resulting empty Hugo website on my local server? How do I select new functionality or content for the site? I understand that the doc has all the answers, but could use a pointer to the right place, please.
It was all packed in “Here things can go wrong if the directory nesting is not correct.”. All the theme contents need to be directly under foo/theme/ananke/ that I mentioned earlier.
IMO just installing git and following the instructions will be a much more pleasant experience.
For me, copying the contents of a directory up a level is a standard operation, one that my 40 years in software engineering prepares me for. GitHub, on the other hand, is impossible for me to understand, even though I’ve found several tutorials. The tutorials are either too simple, so that nothing useful can be done, or too complex for a newcomer to understand. I’m hoping to get to the point where I can see what Hugo can do somewhat soon, but I’m not there yet as I don’t know the next step and I’ve lost my place in the docs… I want to see Hugo working without using GitHub or git (not sure how they differ, either).
Try this (I did this on a GNU/Linux system, but I hope you can find the equivalent commands on Windows):
STEPS:
1. hugo version
2. hugo new site quickstart
3. cd quickstart
4. (download) \wget -rnd https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
5. (extract) dtrx master.zip
6. mv gohugo-theme-ananke-master ananke
7. mv ananke themes/.
8. echo 'theme = "ananke"' >> config.toml
9. hugo new posts/my-first-post.md
10. (local server) hugo server -D
Details
km²~/sandbox/:hugo/quickstart_nogit> hugo version 01/08 12:05pm
Hugo Static Site Generator v0.54-DEV-9DDB80AD:CHROMA-D5CA12B linux/amd64 BuildDate: 2019-01-04T11:07:50-0500
km²~/sandbox/:hugo/quickstart_nogit> hugo new site quickstart 01/08 12:05pm
Congratulations! Your new Hugo site is created in /home/kmodi/sandbox/hugo/quickstart_nogit/quickstart.
Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/, or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.
km²~/sandbox/:hugo/quickstart_nogit> cd quickstart 01/08 12:05pm
km²~/sandbox/:hugo/quickstart_nogit/quickstart> \wget -rnd https://github.com/budparr/gohugo-theme-ananke/archive/master.zip 01/08 12:07pm
--2019-01-08 12:07:21-- https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
Resolving github.com... 192.30.253.113, 192.30.253.112
Connecting to github.com|192.30.253.113|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://codeload.github.com/budparr/gohugo-theme-ananke/zip/master [following]
--2019-01-08 12:07:22-- https://codeload.github.com/budparr/gohugo-theme-ananke/zip/master
Resolving codeload.github.com... 192.30.253.120, 192.30.253.121
Connecting to codeload.github.com|192.30.253.120|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: unspecified [application/zip]
Saving to: “master.zip”
[ <=> ] 1,211,934 1.11M/s in 1.0s
2019-01-08 12:07:23 (1.11 MB/s) - “master.zip” saved [1211934]
FINISHED --2019-01-08 12:07:23--
Downloaded: 1 files, 1.2M in 1.0s (1.11 MB/s)
km²~/sandbox/:hugo/quickstart_nogit/quickstart> dtrx master.zip 01/08 12:07pm
master.zip contains one directory but its name doesn't match.
Expected: master
Actual: gohugo-theme-ananke-master/
You can:
* extract the directory _I_nside a new directory named master
* extract the directory and _R_ename it master
* extract the directory _H_ere
What do you want to do? (I/r/h) h
km²~/sandbox/:hugo/quickstart_nogit/quickstart> mv gohugo-theme-ananke-master ananke 01/08 12:07pm
km²~/sandbox/:hugo/quickstart_nogit/quickstart> mv ananke themes/. 01/08 12:07pm
km²~/sandbox/:hugo/quickstart_nogit/quickstart> echo 'theme = "ananke"' >> config.toml 01/08 12:08pm
km²~/sandbox/:hugo/quickstart_nogit/quickstart> hugo new posts/my-first-post.md 01/08 12:08pm
/home/kmodi/sandbox/hugo/quickstart_nogit/quickstart/content/posts/my-first-post.md created
km²~/sandbox/:hugo/quickstart_nogit/quickstart> hugo server -D
port 1313 already in use, attempting to use an available port
| EN
+------------------+----+
Pages | 10
Paginator pages | 0
Non-page files | 0
Static files | 3
Processed images | 0
Aliases | 1
Sitemaps | 1
Cleaned | 0
Total in 22 ms
Watching for changes in /home/kmodi/sandbox/hugo/quickstart_nogit/quickstart/{content,data,layouts,static,themes}
Watching for config changes in /home/kmodi/sandbox/hugo/quickstart_nogit/quickstart/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:44908/ (bind address 127.0.0.1)
Press Ctrl+C to stop
Thank you, I’m working through the list of git tutorials. I’m finding the same problems as in the past: these tutorials are either too simple or too rapidly complex and must be abandoned. Also, they frequently assume we use Linux command lines to develop websites. I have always used Windows, not Linux, for development and learning, even though my production servers as Linux-based. I find command lines to be brick walls for productivity as compared with keyboard macros and Windows mouse and keyboard operations.
I’ve installed GitHub Desktop and I’m hoping to find a tutorial for it. I don’t know if I’m supposed to use GitHub Desktop or the GitHub website to do development, but so far both are useless until I can find some way to learn how to use them.
You claim to have 40 years of software engineering experience – I’m surprised you haven’t learned at least one version control software in that time. As long as you know one, the concepts carry over to others.
Be careful with your current attitude. It will not bring you very far. I encourage a change of perspective. Instead of trashing online tutorials (that thousands of other users have successfully learned from), stop, and be thankful. Imagine if you had to learn these tools by “man” pages only.
zwbetz, Thanks for your feedback. Yes, I have learned several version control systems along the way. In those ancient days they were not used much by startup and mid-sized companies, with a few exceptions, mostly by large-scale projects in the very largest of companies, like IBM, who had the luxury of using advanced software tools. I’m glad that git has caught on and is used for open software today; I’m certainly a fan in principle.
Yes, I am thankful that our primary source of learning is not man pages. However, I was being honest and open in my comments about the git tutorials I have read so far. As compared with JavaScript, CSS, and HTML tutorials I have found them as I described them. I intend to keep reading and hope I “catch on” to the operations I need to understand soon.
I am very productive when I am designing and coding my own projects, but every now and then I try to learn the latest software technologies and often find them difficult to learn or not really better than older technologies for my purposes (my own purposes being mostly small software tools such as a browser-based password manager, a PHP-based modular website construction tool, and a PHP-based shared security system, among many others).
I am frustrated when I have to pause my active projects for days or weeks to learn the latest JavaScript syntax or the git system, or web technologies like ember and react. I apologize for allowing my frustration to come out in my posts. At least I am honest, and I hope that perhaps my sometimes negative feedback about documentation might have some good result somewhere.
My latest goal was to evaluate Hugo for possible use in my own websites and web-based applications, which was where I hit the git wall. I still do not have a good feel for whether Hugo would work for me (it is certainly perfect in the speed and interactive development departments) or whether I need to resume my waiting project to create a module-oriented static web design tool, where each module can contain an arbitrary mixture of arbitrary programming languages such as HTML, css, and JavaScript, with the output being a single file in each language.
I use Hugo without git, all the time. I don’t use GitHub, personally. Git is not a foundational part of Hugo, it is a large foundation of current development practices. That’s all.
And from helping folks over the last year, I think the only parts you need to learn is how to init, clone, and submodule, to follow the directions most theme authors leave for installing. I personally hardly ever use submodules; I don’t like the conceptual model, so I avoid using them. But I learned how because so many folks around here use them.
Hmmm, I don’t think it is the Hugo project’s job to explain current development practices may be practical requirements, but we sure do get a lot folks coming in claiming this. I’ve never seen that explained in a project, how about you, @zwbetz?
