samsam-ahmadi / blog

http://klug.ir/blog

klug.ir/BLOG

- 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.

---

Posts

• 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 touch 03:30 which is Iran UTC time offset. You may also see 04:30 that is because of detected summer clock on author's OS. When you are still working on your post, set the draft as true. 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.

@Staff

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!

Plan A+

1. Install Hugo: Archlinux (AUR)/Ubuntu (16.04)/'.deb' Packages (optional, recommended)

2. 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.
     

3. Run hugo new post/<date>-<post-title>.md. A new Markdown source would be created within the content/post directory. If hugo is not installed, create <date>-<post-title>.md manually within content/post.

4. 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.

5. 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.

6. 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
   

7. Sign in to GitHub and send a PR, wait to be merged.

Plan A

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.

Plan B

None of the above? Simply send your .md file to hello AT klug D0T ir.