- This repository contains the source code for klug.ir/blog web site.
- Feel free to fix typos or make clarifications with a pull request (PR).
- Contents are converted from Markdown to HTML manually by Hugo static site generator and located in gh-pages branch using this deploy script.
-
Each post must be located in
content/post
-
<date>-<post-title>.md
is the naming structure for blog posts. -
A post should be started with the below snippet (called 'frontmatter') at the beginnig:
+++ author = "Author" categories = [ "Category" ] date = "YYYY-MM-DDThh:mm:ss+03:30" description = "Description" draft = true/false tags = [ "tag1", "tag2" ] title = "Title" +++
YYYY-MM-DD
should be in Gregorian date.hh:mm:ss
refers to time and don't touch03:30
which is Iran UTC time offset. You may also see04:30
that is because of detected summer clock on author's OS. When you are still working on your post, set thedraft
astrue
. Once completed, ensure it’s no longer a draft:hugo undraft content/post/<file-name>.md
or simply replace 'true' with 'false'. -
Images should be kept in
static/img
directory following this naming structure:<post-name>-<image-title>.jpg
. You can use common formats as in jpeg (jpg), png and gif. -
It's not recommended to host videos as the repo size is limited to 1 GB. You can use video streaming services such as Aparat, Youtube, Vimeo, etc.
If you'd like to publish a post, there are 3 plans to do it:
- Plan A+: Dealing with git and command line
- Plan A: Create a post online.
- Plan B: Scroll down to find!
-
Install Hugo: Archlinux (AUR)/Ubuntu (16.04)/'.deb' Packages (optional, recommended)
-
Fork the master repo into your GitHub account. Clone it. Navigate there.
-
Optional: Add upstream as a remote to your local clone:
git remote add upstream https://github.com/kermanlug/blog.git
(upstream here is just a name, arbitrary. It's just the most common name used in this context.)
then:
git fetch upstream #fetches all changes from the original repo git checkout -b new_thing upstream/master #creates a new branch based on the master branch's status of upstream as it was the last time you ran fetch. git rebase upstream/master #reapplies all commits of the current branch that are not in the master branch of upstream on top of the master branch of upstream, again upstream/master being master as it was at last time you fetched.
-
-
Run
hugo new post/<date>-<post-title>.md
. A new Markdown source would be created within thecontent/post
directory. If hugo is not installed, create<date>-<post-title>.md
manually withincontent/post
. -
Open the new created file in your editor, edit the frontmatter and write your post. You can use a barebone editr, a feature-rich editor or even a wysiwyg (live) Markdown editor to work with your post. Here are some Markdown editor:
- UberWriter/Haroopad/Remarkable/Atom extension/GitBook/Emacs Markdown Mode/etc as native desktop clients.
- Browser Plugings: Markdown Preview Plus (Chrom/Chromium) | Markdown Viewer (FF)
- StackEdit/Dillinger/(GitHub-Flavored)_Markdown_Editor/Pen as online editors.
- If you need to draft them in cloud, try Markable.
-
It’s a good idea to preview your work by running:
hugo server
. This will run a full functioning web server while simultaneously watching your file system for additions, deletions or changes. If everything is fine, open a browser to http://localhost:1313/blog/, so that you can see updates as you are working on the post. -
Add and commit the new post in master branch:
git add content/post/<POST_NAME> git commit -m "<YOUR_DESCRIPTION_HERE>, $(date)" git push origin master #Push to your repo
-
Sign in to GitHub and send a PR, wait to be merged.
You can try GitHub web UI to create a page if you don't feel free with command line! Visit conten/post page, take a look at around, you'll see a New file button, press it. Insert your Markdown contents there, commit it and finish your work by sending a PR.
None of the above? Simply send your .md
file to hello AT klug D0T ir
.