FunctionalHacker/hugo-toha
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve theme README & exampleSite (#157)

Browse source 
* Improve theme README

* Update exampleSite

* Add "Available Translation" section in README
This commit is contained in:
Emruz Hossain 2020-11-05 02:11:32 +06:00 • committed by GitHub
parent b39ed5213e
commit 7a05e9b022
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
55 changed files with 283 additions and 239 deletions
Download patch file Download diff file Expand all files Collapse all files

200
README.md
View file

@ -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:
#### 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
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
$ 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 +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`.
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
`static/assets/css/style.css` file and add any custom CSS there.
#### Running Locally
## Usage
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
```
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
```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