Improve theme README

README.md

@@ -4,57 +4,72 @@
 
 A [Hugo](https://gohugo.io/) theme for a personal portfolio with minimalist design and responsiveness.
 
-![Thumbnail](https://github.com/hugo-toha/toha/blob/master/images/tn.png)
+![Thumbnail](https://raw.githubusercontent.com/hugo-toha/toha/master/images/screenshot.png)
+
+**Example Site:** [hugo-toha.github.io](https://hugo-toha.github.io)
+**Documentation:** [toha-guides.netlify.app](https://toha-guides.netlify.app/posts)
 
-Example Site: [hugo-toha.github.io](https://hugo-toha.github.io)
-Documentation: [toha-guides.netlify.app](https://toha-guides.netlify.app/posts)
 
 ## Features
 
 - Minimalist Design
 - Fully Responsive
-- Carefully designed cards
+- Multiple Language Support
-- Great Experience timeline
+- Carefully Designed Cards
-- Achievement gallery
+- Experience Timeline
-- Sidebar to categorize posts
+- Achievement Gallery
+- Sidebar to Categorize the Posts
 - Short Codes
 - Google Analytics Support
 - Disqus Comment Support
 
 For more details about the features please visit [here](https://toha-guides.netlify.app/posts/features/).
 
-## Requirements
+## Screenshots
+
+Here, are few screenshot from the [example site](https://hugo-toha.github.io).
+
+##### Home Page Sections
+
+![Home Page Sections](https://raw.githubusercontent.com/hugo-toha/toha/master/images/about.png)
+
+##### List Page
+
+![List Page](https://raw.githubusercontent.com/hugo-toha/toha/master/images/list.png)
+
+##### Reading Page
+
+![Reading Page](https://raw.githubusercontent.com/hugo-toha/toha/master/images/single.png)
+
+### Requirements
 
 - Hugo Version 0.68.0 or higher
 
-## Installation
+### Usage
 
-- Create your site if you haven't already
+In order to use this theme, follow the following steps:
+
+#### Add theme as git submodule
+
+At first, add [Toha](https://github.com/hugo-toha/toha) theme as git submodule to your hugo-site.
 
 ```console
-hugo new site my-site -f=yaml
+$ git submodule add https://github.com/hugo-toha/toha.git themes/toha
-cd my-site
-git init
-```
-
-- Add the theme as git sub-module
-
-```console
-git submodule add https://github.com/hugo-toha/toha.git themes/toha
 ```
 
 >Don't use SSH URL of the theme during adding as git sub-module. Also, don't clone the theme in your `themes` directory using `git clone`. They don't work well with Github Action or Netlify.
 
-If you want to customize the theme templates, then fork it and use the fork as your theme.
+If you don't already have a hugo site, create one by following the step by step guide from [here](https://toha-guides.netlify.app/posts/getting-started/prepare-site/).
 
-## Configuration
+#### Configuring Site
 
-Configure your `config.yaml` file of your site as below:
+Now, configure your site to use `toha` theme by adding the following configuration in `config.yaml` file of your site.
 
 ```yaml
-baseURL: http://example.org/
+baseURL: https://hugo-toha.github.io
+
 languageCode: en-us
-title: "Toha"
+title: "John's Blog"
 theme: "toha"
 
 # Manage languages
@@ -63,52 +78,23 @@ languages:
   en:
     languageName: English
     weight: 1
-  fr:
-    languageName: Français
-    weight: 2
-  bn:
-    languageName: বাংলা
-    weight: 3
 
-# Force a locale to be use, really useful to develop the application ! Should be commented in production, the "weight" should rocks.
+# Control TOC depth
-# DefaultContentLanguage: fr
-
-# Allow raw html in markdown file
 markup:
-  goldmark:
-    renderer:
-      unsafe: true
   tableOfContents:
     startLevel: 2
     endLevel: 6
     ordered: false
 
-# Enable Google Analytics
-googleAnalytics: UA-XXXXXXXXX-X
-
-# Enable Disqus forum
-disqusShortname: does-not-exist
-
 # Enable global emoji support
 enableEmoji: true
 
-# Custom parameters
+# Site parameters
 params:
-  # background image of the landing page
-  background: "images/background.jpg"
-
-  # Provide logos for your site. The inverted logo will be used in the initial
-  # transparent navbar and the main logo will be used in the non-transparent navbar.
-  # It will be default to the theme logos if not provided.
-  logo:
-    main: /assets/images/main-logo.png
-    inverted: /assets/images/inverted-logo.png
-    favicon: /assets/images/favicon.png
-
   # GitHub repo URL of your site
-  gitRepo: https://github.com/hugo-toha/toha-example-site
+  gitRepo: https://github.com/hugo-toha/hugo-toha.github.io
 
-  # specify whether you want to write blog post or not
+  # specify whether you want to write some blog posts or not
   enableBlogPost: true
 
   # specify whether you want to show Table of Contents in reading page
@@ -120,31 +106,26 @@ params:
     enable: true
 ```
 
-You can just copy the content for `config.yaml` files from `theme/toha/exampleSite/config.yaml`.
+Don't forget to update `title`, `baseURL`, and `gitRepo` fields with your own information. To know about more available configuration options, please visit [here](https://toha-guides.netlify.app/posts/configuration/site-parameters/).
 
-If you want to customize the any of the CSS styles on your site, create a
+#### Running Locally
-`static/assets/css/style.css` file and add any custom CSS there.
 
-## Usage
+Now, you can run your hugo site with `toha` theme locally with the following command:
-
-Run your hugo site with this theme.
 
 ```console
-hugo server -w
+$ hugo server -t toha -w
 ```
 
-When you first run your site, it will start with the default parameters. It should look similar to the [example site](https://toha.netlify.app) except it will not have any sections in the homepage. Those sections are added via some data files.
+When you run your site for first time, it will start with the default parameters. It should look similar to the [example site](https://hugo-toha.github.io). However, it will not have any sections in the homepage as we haven't configured them yet. You can configure your site by following the guides from [here](https://toha-guides.netlify.app/posts/configuration/).
-
-You can configure your site by following the step by step guides from [here](https://toha.netlify.app/posts/configuration/).
 
 ## Shortcodes
 
 Here, are some handy shortcodes you can use with this theme.
 
-- [img](https://toha.netlify.app/posts/short-codes/img/)
+- [Alert](https://toha-guides.netlify.app/posts/short-codes/alert/)
-- [split](https://toha.netlify.app/posts/short-codes/split/)
+- [Image](https://toha-guides.netlify.app/posts/short-codes/img/)
-- [vs](https://toha.netlify.app/posts/short-codes/vs/)
+- [Split](https://toha-guides.netlify.app/posts/short-codes/split/)
-- [alert](https://toha.netlify.app/posts/short-codes/alert/)
+- [Vertical Space](https://toha-guides.netlify.app/posts/short-codes/vs/)
 
 ## Project Roadmap
 
@@ -188,6 +169,14 @@ Here, are the current plan and progress of various components of this theme. The
 
 - [x] **Recent Posts**
 
+- [ ] **Academic Career**
+  - [ ] Degree
+  - [ ] Institution
+  - [ ] Timeline
+  - [ ] Taken Courses
+  - [ ] CGPA
+  - [ ] Extracurricular Activities
+
 - [ ] **Publications**
   - [ ] Category Filter
   - [ ] Card
@@ -215,10 +204,11 @@ Here, are the current plan and progress of various components of this theme. The
 
 - [x] Hero Image
 - [x] Author Information
+- [x] Sidebar
+- [x] Table of Contents
 - [x] Next & Previous Page Navigation
 - [x] `Improve This Page` Button
 - [x] Disqus Comment
-- [x] Option to navigate to list page
 
 ### Tracking and Comments
 
@@ -245,34 +235,62 @@ Pull requests are most welcome and I will be happy to review. Just follow the fo
 - Use as few dependencies as possible.
 - Have patience.
 
->I am not a web developer. I just created this theme for my personal needs. So, it is reasonable to have some flaws in the codes. Feel free to open issues and PR acknowledging the problems.
+>I am not a web developer. I have created this theme for my personal needs. So, it is reasonable to have some flaws in the codes. Feel free to open issues and PRs acknowledging the problems.
 
 ## Local Development
 
-For local development, you can run your own site or the [example site](https://github.com/hugo-toha/toha-example-site) locally and make changes in the theme submodule.
+For local development, you can make changes in the theme submodule and test the changes against your own site or this [example site](https://github.com/hugo-toha/hugo-toha.github.io) locally.
 
 ### Fork
-Fork [this repo](https://github.com/hugo-toha/toha) and setup your local submodule with the following from the site's folder by running the following
 
-```sh
+At first, fork [this repo](https://github.com/hugo-toha/toha). Then, follow the following steps to use the forked theme for local developments,
-git submodule update --init --recursive --remote
+
-cd themes/toha
+**Using the forked theme in your own site:**
-git remote add my-fork https://github.com/<your-github-user>/toha
+
-git checkout -b my-feature-branch
+If you want to run your local development against your own site, follow the following steps:
+
+```bash
+# add the original theme as a submodule of your site if you haven't done already
+$ git submodule add https://github.com/hugo-toha/toha.git themes/toha
+# navigate into the toha theme folder
+$ cd themes/toha
+# add your own fork as a remote
+$ git remote add my-fork https://github.com/<your-github-user>/toha
+# create a new branch for your changes
+$ git checkout -b my-feature-branch
 ```
 
-From there you can make changes to the source code of the theme while testing with your running Hugo site.
+**Using the forked theme in the example site:**
+
+If your want to run your local development against this [example site](https://github.com/hugo-toha/hugo-toha.github.io), follow the following steps:
+
+```bash
+# clone the example site along with the submodules
+$ git clone git@github.com:hugo-toha/hugo-toha.github.io.git --recursive
+# navigate into the toha theme folder
+$ cd themes/toha
+# add your own fork as a remote
+$ git remote add my-fork https://github.com/<your-github-user>/toha
+# create a new branch for your changes
+$ git checkout -b my-feature-branch
+```
+
+From there you can make changes to the source code of the theme while testing with your running Hugo site or the example site.
 
 ### Open a PR
 
-When the changes look good, commit and push them to your fork
+When the changes look good, commit and push them to your fork.
-```sh
+
-git add .
+```bash
-git commit -m "A meaningful commit message"
+# stage all the changes
-git push my-fork my-feature-branch
+$ git add .
+# commit the changes with a meaning full commit message
+$ git commit -m "A meaningful commit message"
+# push the commit to your fork
+$ git push my-fork my-feature-branch
 ```
 
-And then open a PR `https://github.com/<your-github-user></your-github-user>/toha/pull/new/my-feature-branch`
+Then, open a PR against `master` branch of [hugo-toha/toha](https://github.com/hugo-toha/toha) from the `my-feature-branch` branch of your own fork.
 
 ## Attribution