harms-columns-front-page 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3dc4e6b63484ad051332950588ecd2e79bb58561
-  data.tar.gz: 6dd5d8bfa874cfbb51ab8e192e032e256f455e7c
+  metadata.gz: eb54a65b9580490d09900992d8fbf0346b09b2be
+  data.tar.gz: 393a296e9b6088262ae2a4832438a557b5da08db
 SHA512:
-  metadata.gz: 29a4c17f07ecd32cfa8f138ec63040bad35e3cc0a8b15716ed517ecc295f0f1742f2b19ba44bcd82ee17d902a52e388bcd310be879829a24499438ab05cec72e
-  data.tar.gz: b207fb2c5bf9031a2808661f77a5b20857680227faea1c4983a5ec8ca7306b99b6a89946938b94b23f3a9ee4091d3b4ed5e65809ca669264a9e5745bff957a5a
+  metadata.gz: 55dbdd8fdac87c412bc7bc0a404ccb618a1b1a6442e787cde6406d9dbe0224e969edfccc08dd644417483c9b605e26af7181e750b89df169d03700ea3de089f6
+  data.tar.gz: ab165388fdfa9982dbfe8199df87ec8a1fafeea73ae320693a4f5e92571982c66a2914bd551f560ee8a27a47ba9195590b6b94f3f0fefcccc72361b91f90ffb1

data/README.md

@@ -1,70 +1,139 @@
-# harms-columns-front-page
+# harms-columns-front-page [![Gem Version](https://badge.fury.io/rb/harms-columns-front-page.svg)](https://badge.fury.io/rb/harms-columns-front-page)
 
 This Jekyll theme was developed as part of a bachelor thesis.
 
-Jekyll is a static site generator based on ruby.
+Jekyll is a static site generator based on ruby. For more information visit <https://jekyllrb.com/>.
+
+<br>
 
 ## How to install Jekyll
+
+<br>
+
 ### On Windows
-Step 1: Download the latest ruby installer from <https://rubyinstaller.org/> and install ruby.
+This guide is based on [this article](https://davidburela.wordpress.com/2015/11/28/easily-install-jekyll-on-windows-with-3-command-prompt-entries-and-chocolatey/) by David Burela.
+
+
+**Step 1:** Install the chocolatey package manager by following [these instructions](https://chocolatey.org/install) on their site.
+
+**Step 2:** Install Ruby by running the following command in the command prompt:
+
+    choco install ruby -y
+
+Make sure you install all 3 MSYS2 components when a new command prompt window opens with the Ruby Installer.
+
+**Step 3:** Install Bundler by running:
+
+    gem install bundler
+
+**Step 4:** And finally you can install Jekyll by running:
+
+    gem install jekyll
+
+And now you're ready to go with Jekyll!
 
-Step 2: Open your terminal and execute the following commands:
+<br>
 
-First install Jekyll by running:
+### On Linux
+
+This guide is based on Step 1 of [this tutorial](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-jekyll-development-site-on-ubuntu-16-04) by Melissa Anderson. I have not yet tested it myself.
+
+**Step 1:** Update your package list by running the following command in the terminal:
+
+    sudo apt-get update
+
+**Step 2:** Install Ruby, make and gcc by running:
+
+    sudo apt-get install ruby ruby-dev make gcc
+
+**Step 3:** Install Jekyll and Bundler by running:
+
+    sudo gem install jekyll bundler
+
+And now you're ready to go with Jekyll!
+
+<br>
+
+### On Mac
+If you're using a Mac, then Ruby should already be installed on your machine.
+
+**Step 1:** Run the following command to install Jekyll and Bundler:
 
     gem install jekyll bundler
 
-Then make a new Jekyll project by running:
+And that's it, you're ready to go with Jekyll!
+
+<br>
+
+## How to create a Jekyll site
 
-    jekyll new your-project-name
+**Step 1:** Run the following command in the command prompt to create a new Jekyll project:
 
-Then enter the project directory by running:
+    jekyll new project-name
 
-    cd your-project-name
+**Step 2:** Enter the project directory by running:
 
-You can test your jekyll site by running:
+    cd project-name
+
+**Step 3:** Run the following command to build your Jekyll site and preview it locally under <http://localhost:4000>.
 
     bundle exec jekyll serve
 
-Now you can head over to <http://localhost:4000> in your browser and view your jekyll site.
+The files for your website are located in the `_site` folder inside of your project folder.
+
+<br>
 
 ## How to install the theme
 
-Step 1: Add this line to the bottom of your Jekyll site's `Gemfile`:
+**Step 1:** Add this line to the bottom of your Jekyll site's `Gemfile`:
 
 ```ruby
 gem "harms-columns-front-page"
 ```
-Step 2: Install the theme by running this in the terminal:
+**Step 2:** Install the theme by running this in the terminal:
 
     bundle
 
-Step 3: Add this lines to the bottom of your Jekyll site's `_config.yml`:
+**Step 3:** In your Jekyll site's `_config.yml`, find the line that starts with `theme:` and replace it with this line:
 
 ```yaml
 theme: harms-columns-front-page
+```
+
+**Step 4:** Then find the section that starts with `gem:` and add the following entries to the list: 
+
+```yaml
 gems:
-  - jekyll-lunr-js-search
+  - jekyll-autoprefixer
+  - jekyll-minifier
 ```
 
-Step 4: And then run the following command in the terminal:
+**Step 5:** Run the following command in the terminal:
 
     bundle exec jekyll serve
 
 Now you can head over to <http://localhost:4000> in your browser and view the new theme on your jekyll site.
 
+<br>
+
 ## Updating
 
 If you've already installed this theme for your Jekyll site, you can update it by running the following command in the terminal:
 
     bundle update
 
+<br>
+
 ## Usage
 
+<br>
+
 ### Global options
 The following options are available to use in your Jekyll site's `_config.yml`.
 
-**Site Title**
+<br>
+
+#### _Site Title_
 
 Appears in the header and as the title of your browser window.
 
@@ -72,7 +141,9 @@ Appears in the header and as the title of your browser window.
 title: Your title here
 ```
 
-**Site Description**
+<br>
+
+#### _Site Description_
 
 This is the meta description of your site.
 
@@ -80,15 +151,79 @@ This is the meta description of your site.
 description: Your site description here.
 ```
 
-**Profile Image**
+<br>
+
+#### _Profile/Logo Image_
 
-This image will appear as a little profile image in your header.
+This image will appear as a little profile or logo image in your header.
 
 ```yaml
 profile-image: path/to/your/image/here.jpg
 ```
 
-**Favicon**
+<br>
+
+#### _Site Language_
+
+Sets the language attribute of the html element of your site. This is important for search engines and browsers.
+
+```yaml
+lang: en
+```
+
+<br>
+
+#### _Color of the header_
+
+You can customize the background color of the header. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:
+
+```yaml
+header-color: '#2FEB8D'
+```
+
+<br>
+
+#### _Color of the front page columns_
+
+You can customize the background color of the columns on the front page. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:
+
+```yaml
+columns-color: '#FFFFFF'
+```
+
+<br>
+
+#### _Color of the site's h1_
+
+You can customize the color of the site's h1 heading. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:
+
+```yaml
+h1-color: '#282828'
+```
+
+<br>
+
+#### _Color of the site's h2_
+
+You can customize the color of the site's h2 heading. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:
+
+```yaml
+h2-color: '#2FEB8D'
+```
+
+<br>
+
+#### _Color of the site's links and buttons_
+
+You can customize the color of the site's links and buttons. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:
+
+```yaml
+link-color: '#12ADFF'
+```
+
+<br>
+
+#### _Favicon_
 
 The favicon will appear as the icon alongside the title of your site in the browser window. Please use a png-file.
 
@@ -96,7 +231,9 @@ The favicon will appear as the icon alongside the title of your site in the brow
 favicon: path/to/your/favicon/here.png
 ```
 
-**Subtitle**
+<br>
+
+#### _Subtitle_
 
 The subtitle will appear in your header under the site title.
 
@@ -104,18 +241,11 @@ The subtitle will appear in your header under the site title.
 subtitle: Your subtitle here
 ```
 
-**Social Links**
+<br>
 
-The links to your social profiles will appear in the footer of your site. You have to specify a title and the link url like so:
+#### _Social Links_
 
-```yaml
-social:
-  - title: Link 1
-    url: http://www.your-first-link-here.com
-  - title: Link 2
-    url: http://www.your-second-link-here.com
-```
-Optionally you can specify the path to an icon that should be used for the link instead of the title.
+The links to your social profiles will appear in the footer of your site. You have to specify a title and the link url. Optionally you can specify the path to an icon that should be used for the link instead of the title.:
 
 ```yaml
 social:
@@ -127,16 +257,22 @@ social:
     icon: path/to/social/icon/1.jpg
 ```
 
-**Footer Copyright Text**
+<br>
+
+#### _Footer Copyright Text_
 
 You can add your name to the copyright section in the footer.
 
 ```yaml
 footer-copyright: Year and name here
 ```
-**Home columns**
+
+<br>
+
+#### _Home columns_
 
 Here you can add content for the column section on the home page. You have to specify a heading and the content. The button url is optional: if it is not set, there will be no button for that column on your site.
+
 ```yaml
 home-columns:
   - heading: Your heading 1 here
@@ -152,32 +288,245 @@ home-columns:
     button-url: http://www.your-link-3-here.com
 ```
 
-### Page and posts options
+<br>
+
+### Page options
+
+The following options are available to use in each of your Jekyll site's pages front matter.
 
-The following options are available to use in each of your Jekyll pages or posts front matter.
+<br>
 
-**Layout**
+#### _Accordion for saving space_
 
-You can specify a layout for a page/post like this:
+If you're having a page that contains large amounts of contents, you can save space by displaying them as an accordion. The sections of the accordion can be opened and closed. No configuration in the front matter is needed. Simply use this syntax in your page's markdown:
+
+```markdown
+<div id="accordion" markdown="block">
+
+### Section 1 heading
+<div markdown="block">
+Section 1 content
+</div>
+
+### Section 2 heading
+<div markdown="block">
+Section 2 content
+</div>
+
+### Section 3 heading
+<div markdown="block">
+Section 3 content
+</div>
+
+</div>
+```
+
+<br>
+
+#### _Layout_
+
+You can specify a layout for a page like this:
 
 ```yaml
 layout: layout-name-here
 ```
 
 The available layouts are:
-* `home`: Default layout for the home page
-* `page`: Default layout for subpages
-* `post`: Default layout for posts
+* `home` - for the front page
+* `page` - for pages
+* `post` - for posts
 
-**Title**
+<br>
 
-This specifies the title of your page/post, which will appear on top of the page/post (except for the home page) and in the title of your browser window behind your site title.
+#### _Featured image_
+
+You can specify a path to a featured image for a page. It will then be used instead of the default header.
 
 ```yaml
-title: Your page/post title here
+featured-image: /assets/img/your-image.jpg
 ```
 
-TODO: Write further options for the posts and pages.
+<br>
+
+#### _Title_
+
+This specifies the title of your page, which will appear on top of the page (except for the front page) and in the title of your browser window behind your site title.
+
+```yaml
+title: Your page title here
+```
+
+<br>
+
+#### _Permalink_
+
+This specifies the permalink of your page and therefore the url your page will be avaialable at (www.your-site-name.com/your-page-permalink-here)
+
+```yaml
+permalink: /your-page-permalink-here/
+```
+
+<br>
+
+#### _Display the page in the navigation menu_
+
+With this variable you can specify if this page should appear in one of the navigation menus. If you don't specify this variable, the page won't be accessible over any navigation menu. To place a page in the main navigation located on top of the screen, use this line:
+
+```yaml
+nav: main
+```
+
+To place a page in the navigation links down in the footer, use this line:
+
+```yaml
+nav: footer
+```
+
+<br>
+
+#### _Order of the navigation menus_
+
+If you want to have your pages in a navigation menu in a specific order you can archieve this by assigning positions to every one of them.
+
+```yaml
+nav-position: 1
+```
+
+<br>
+
+#### _Show post list on a page_
+
+If you want to display a list of posts beneath the main content of a page, you can do this by setting a variable with the category of posts you want to show. If the variable is not set, the page will not have blog posts on it.
+
+```yaml
+show-category: News
+```
+
+Simultaneously you can specify a maximum number of posts to display. When this variable is not set, all posts of the category are displayed.
+
+```yaml
+post-limit: 3
+```
+
+<br>
+
+#### _Filter posts by tag_
+
+If you're displaying a post list on a page and you want to give your site's visitors the ability to filter that list by different tags, you can do this by setting this variable. A list of buttons with the different tags to choose from will appear:
+
+```yaml
+tag-filter: true
+```
+
+Simultaneously you should specify the text that should be used for the button that shows all posts again after filtering, like so:
+
+```yaml
+show-all-filter-label: Show all posts
+```
+
+<br>
+
+### Post options
+
+<br>
+
+#### _Accordion for saving space_
+
+If you're having a post that contains large amounts of contents, you can save space by displaying them as an accordion. The sections of the accordion can be opened and closed. No configuration in the front matter is needed. Simply use this syntax in your post's markdown:
+
+```markdown
+<div id="accordion" markdown="block">
+
+### Section 1 heading
+<div markdown="block">
+Section 1 content
+</div>
+
+### Section 2 heading
+<div markdown="block">
+Section 2 content
+</div>
+
+### Section 3 heading
+<div markdown="block">
+Section 3 content
+</div>
+
+</div>
+```
+
+<br>
+
+#### _Featured image_
+
+You can specify a path to a featured image for a post. It will then be used instead of the default header and as a preview image in lists in which the post appears.
+
+```yaml
+featured-image: /assets/img/your-image.jpg
+```
+
+<br>
+
+#### _Layout_
+
+You can specify a layout for a post like this:
+
+```yaml
+layout: layout-name-here
+```
+
+The available layouts are:
+* `home` - for the front page
+* `page` - for pages
+* `post` - for posts
+
+<br>
+
+#### _Title_
+
+This specifies the title of your post, which will appear on top of the page (except for the front page) and in the title of your browser window behind your site title. Also it appears as the post title in post listings.
+
+```yaml
+title: Your post title here
+```
+
+<br>
+
+#### _Publishing date_
+
+If a publishing date is set for your post, it will be displayed alongside the content.
+
+```yaml
+publishing-date: 27.10.2016
+```
+
+<br>
+
+#### _Category_
+
+You can specify a category to which a post belongs. You can then display all posts of a blog-category on a page for example.
+
+```yaml
+category: Events
+```
+
+<br>
+
+#### _Tags_
+
+You can specify tags for posts as something like subcategories. They can be used to filter posts of the same category in a post list.
+
+```yaml
+tags: Tournament
+```
+
+One post can have multiple tags. Please specify them as a list like so:
+
+```yaml
+tags:
+  - Tournament
+  - Football
+```
 
 <!-- ## Contributing
 
@@ -191,6 +540,8 @@ Your theme is setup just like a normal Jekyll site! To test your theme, run `bun
 
 When your theme is released, only the files in `_layouts`, `_includes`, and `_sass` tracked with Git will be released. -->
 
+<br>
+
 ## License
 
 The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).