So I released my first Hugo them few days ago, Minimist. A minimal theme I developed for my blog and open-sourced it. It currently supports Google Analytics, RSS, Favicon, code highlighting and it is responsive and SEO friendly. However, It’s still a beta release. So I’m working on adding some needed features like Disqus support, contact/newsletter forms, RTL support, internationalization and many more.
I’m not going to talk about the process of developing Minimist here (I may do it later), instead I want to pinpoint few of the things I learned in this project for future reference.
Project-wise
Makefiles
A Makefile is a file that holds sequences of shell commands that can be triggered with one command. make 'keyword'.
build: clean
hugo --source exampleSite
demo:
hugo server --buildDrafts --source exampleSite
clean:
rm -rf public
rm -rf demo
If you tend to forget specific commands or flags that are important to your project, then Makefiles can be used to create aliases. If you want to run build commands for an automated continuous deployment line then Makefiles can organize your build commands.
Netlify’s build
Netlify can host your static websites for free, not only that, but also can be used as continuous deployment platform. You can deploy branches, pull requests or production ready versions automatically. I currently use Netlify to host Minimist’s demo. It loads the content from ./exampleSite and uses the repo theme files to build the site once I commit to master.
NPM scripts
If you’re using NPM to manage your dependencies, then you must utilize the scripts field in the project’s package.json. Scripts object holds multiple one-line commands (concatenate paralleled commands with an & ). NPM scripts have specific names, and specific roles. For example I usually start my development server with npm run start which runs my webpack dev-server webpack-dev-server --mode=development. Or start instances of Pug + Sass compilers pug -P --watch src/index.pug & sass --watch src/main.sass src/main.css with npm run dev.
Try yarn
They say it has some cool features. Idk for now.
How to tag software releases in Github
There are two ways to add a release tag to a specific version of a software. One is general and used for all Git based systems. The other is to specify it within Github interface (from the releases tab choose ‘Draft a new release’). I found the latter to be better if your repository is on Github, especially if you are using version badges in README.
Hugo docs is your friend
In case you’re developing for Hugo. The documentation has almost all of what you need, just understand the fundamentals first.
Hugo Single vs List
A list page template represents a section’s homepage, it usually lists all single pages within it (think a blog section). A single page template represents your regular content page (think a blog post). Now, you need to understand how content organization matter in Hugo:
/content
about.md //<- single page template, example.com/about
/blog
_index.md //<- list page template, example.com/blog
blog-post.md //<- single page template, example.com/blog/blog-post
/special-posts //<- list page template, example.com/blog/special-posts
special-post.md //<- single page template, example.com/blog/sepcial-posts/special-post
/blog-without-index-md //<- list page template, example.com/blog-without-index-md
normal-post.md //<- single page template, example.com/blog-without-index-md/normal-post
Rule of thumb: A folder will use the list template, an ‘.md’ file will use the single template. (_index.md is a special file in Hugo)
Learn
If you are developing a theme for the first time for a specific platform, then use existing open-source themes for that platform to learn how to accomplish specific parts or the general management of a project.
Teach
Once you feel comfortable developing for a specific platform, help others.
- Answer questions on StackOverflow, it will help you too.
- Open-source your theme and add it to Hugo themes.
- Contribute to Hugo docs.
CSS-wise
CSS Methodologies
If you are using CSS, then invest some time in learning at least one CSS writing methodology and stick to it within your project. Spaghetti CSS is the worst. Search google for “CSS methodologies” as a start.
Flexbox vs. Grid
The rule of thumb to know which to use is that Flexbox used for laying out one-dimension elements (think columns OR rows), Grid is used for two-dimensions (think columns AND rows). So it is actually fine to style your page’s main elements using flex.
Auto margins and Flexbox
Here is a quick trick, if you want an element to be positioned at the end of your flex direction, then add an auto margin between the element and the rest of the elements. I use this trick to stick the page’s footer to the end of the page even if the main content is shorter than screen size.
If you have a correction/suggestion, please tweet me.
– Omar