Improve theme README & exampleSite (hugo-toha#157)

* Improve theme README

* Update exampleSite

* Add "Available Translation" section in README

.github/workflows/md-link-checker.yml

@@ -0,0 +1,13 @@
+name: Check Markdown links
+
+# Run action on pull request event
+on: [pull_request]
+
+jobs:
+ markdown-link-check:
+ runs-on: ubuntu-latest
+ steps:
+ # checkout to latest commit
+ - uses: actions/checkout@master
+ # run markdown linter
+ - uses: gaurav-nelson/github-action-markdown-link-check@v1

README.md

@@ -4,57 +4,82 @@
 
 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
-- Great Experience timeline
-- Achievement gallery
-- Sidebar to categorize posts
+- Multiple Language Support
+- Carefully Designed Cards
+- Experience Timeline
+- 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/).
 
+## Available Translations
+
+- English
+- বাংলা
+- Français
+- Indonesian
+- Deutsch
+- Spanish
+
+To know more about how to translate your site, please visit [here](https://toha-guides.netlify.app/posts/translation/). Follow, the data and post format from this [example site](https://hugo-toha.github.io).
+
+## 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:
 
-```console
-hugo new site my-site -f=yaml
-cd my-site
-git init
-```
+#### Add theme as git submodule
 
-- Add the theme as git sub-module
+At first, add [Toha](https://github.com/hugo-toha/toha) theme as git submodule to your hugo-site.
 
 ```console
-git submodule add https://github.com/hugo-toha/toha.git themes/toha
+$ 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:https://example.org/
+baseURL: https://hugo-toha.github.io
+
 languageCode: en-us
-title: "Toha"
+title: "John's Blog"
 theme: "toha"
 
 # Manage languages
@@ -63,52 +88,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.
-# DefaultContentLanguage: fr
-
-# Allow raw html in markdown file
+# Control TOC depth
 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 +116,26 @@ params:
  enable: true
 ```
 
-You can just copy the content for `config.yaml` files from `theme/toha/exampleSite/config.yaml`.
-
-If you want to customize the any of the CSS styles on your site, create a
-`static/assets/css/style.css` file and add any custom CSS there.
+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/).
 
-## Usage
+#### Running Locally
 
-Run your hugo site with this theme.
+Now, you can run your hugo site with `toha` theme locally with the following command:
 
 ```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.
-
-You can configure your site by following the step by step guides from [here](https://toha.netlify.app/posts/configuration/).
+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/).
 
 ## Shortcodes
 
 Here, are some handy shortcodes you can use with this theme.
 
-- [img](https://toha.netlify.app/posts/short-codes/img/)
-- [split](https://toha.netlify.app/posts/short-codes/split/)
-- [vs](https://toha.netlify.app/posts/short-codes/vs/)
-- [alert](https://toha.netlify.app/posts/short-codes/alert/)
+- [Alert](https://toha-guides.netlify.app/posts/short-codes/alert/)
+- [Image](https://toha-guides.netlify.app/posts/short-codes/img/)
+- [Split](https://toha-guides.netlify.app/posts/short-codes/split/)
+- [Vertical Space](https://toha-guides.netlify.app/posts/short-codes/vs/)
 
 ## Project Roadmap
 
@@ -188,6 +179,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 +214,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 +245,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
-git submodule update --init --recursive --remote
-cd themes/toha
-git remote add my-fork https://github.com/<your-github-user>/toha
-git checkout -b my-feature-branch
+At first, fork [this repo](https://github.com/hugo-toha/toha). Then, follow the following steps to use the forked theme for local developments,
+
+**Using the forked theme in your own site:**
+
+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
+```
+
+**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 [email protected]: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.
+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
-```sh
-git add .
-git commit -m "A meaningful commit message"
-git push my-fork my-feature-branch
+When the changes look good, commit and push them to your fork.
+
+```bash
+# stage all the changes
+$ 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
 

exampleSite/config.yaml

@@ -9,19 +9,21 @@ languages:
  en:
  languageName: English
  weight: 1
- fr:
- languageName: Français
- weight: 2
  bn:
  languageName: বাংলা
+ weight: 2
+ fr:
+ languageName: Français
  weight: 3
- de:
- languageName: Deutsch
- weight: 4
  id: 
  languageName: Indonesian
+ weight: 4
+ de:
+ languageName: Deutsch
  weight: 5
-
+ es:
+ languageName: Spanish
+ weight: 6
 
 # Force a locale to be use, really useful to develop the application ! Should be commented in production, the "weight" should rocks.
 # DefaultContentLanguage: fr
@@ -45,23 +47,23 @@ 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"
+ # Background image of the landing page
+ background: /images/site/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.
+ # It will 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
+ main: /images/site/main-logo.png
+ inverted: /images/site/inverted-logo.png
+ favicon: /images/site/favicon.png
 
  # GitHub repo URL of your site
- gitRepo: https://github.com/hossainemruz/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