src/about.md

   1 ---
   2 layout: page
   3 title: "About"
   4 permalink: /about/
   5 ---
   6
   7 whiteglass is a minimal, responsive Jekyll theme for hackers.
   8
   9 ## Installation
  10
  11 Add this line to your Jekyll site's Gemfile:
  12
  13 ``` ruby
  14 gem "jekyll-whiteglass"
  15 ```
  16
  17 And add this line to your Jekyll site's `_config.yml`:
  18
  19 ``` yaml
  20 theme: jekyll-whiteglass
  21 ```
  22
  23 And then execute:
  24
  25 ``` sh
  26 bundle
  27 ```
  28
  29 Or install it yourself as:
  30
  31 ``` sh
  32 gem install jekyll-whiteglass
  33 ```
  34
  35 ## Quick Start
  36
  37 1. Generate a new Jekyll blog:
  38
  39    ``` sh
  40    jekyll new blog --skip-bundle
  41    cd blog
  42    ```
  43
  44 2. Edit `Gemfile` to use whiteglass theme:
  45
  46    ``` ruby
  47    gem "jekyll-whiteglass"
  48    ```
  49
  50 3. Edit `_config.yml` to use whiteglass theme and its plugins:
  51
  52    ``` yaml
  53    theme: jekyll-whiteglass
  54    plugins:
  55      - jekyll-archives
  56      - jekyll-paginate
  57      - jekyll-sitemap
  58
  59    permalink: /:year/:month/:day/:title/
  60    paginate_path: /posts/:num/
  61    paginate: 5
  62
  63    jekyll-archives:
  64      enabled:
  65        - categories
  66        - tags
  67      layout: category_archives
  68      permalinks:
  69        category: /categories/:name/
  70        tag: /tags/:name/
  71    ```
  72
  73 4. Copy
  74    [`index.html`](https://github.com/yous/whiteglass/blob/master/index.html),
  75    [`about.md`](https://github.com/yous/whiteglass/blob/master/about.md),
  76    [`archives.md`](https://github.com/yous/whiteglass/blob/master/archives.md),
  77    [`feed.xml`](https://github.com/yous/whiteglass/blob/master/feed.xml), and
  78    [`_data/navigation.yml`](https://github.com/yous/whiteglass/blob/master/_data/navigation.yml)
  79    from the theme:
  80
  81    ``` sh
  82    rm index.md
  83    curl -L -O "https://github.com/yous/whiteglass/raw/master/{index.html,about.md,archives.md,feed.xml}"
  84    curl -L --create-dirs -o _data/navigation.yml https://github.com/yous/whiteglass/raw/master/_data/navigation.yml
  85    ```
  86
  87 5. Install gems and you're good to go! The blog will be available on
  88    `http://127.0.0.1:4000`.
  89
  90    ``` sh
  91    bundle install
  92    bundle exec jekyll serve
  93    ```
  94
  95 ## Deployment to GitHub Pages using Travis CI
  96
  97 This theme uses [jekyll-archives](https://github.com/jekyll/jekyll-archives) gem
  98 which is [not supported by GitHub Pages](https://help.github.com/articles/configuring-jekyll-plugins/).
  99 If you want to use full features like categories and tags, I recommend you to
 100 use Travis CI or other CI services.
 101
 102 To deploy using Travis CI, first copy the [`.travis.yml`](https://github.com/yous/whiteglass/blob/master/.travis.yml)
 103 of this repository. You can change `target-branch` (`gh-pages` by default) and
 104 `on.branch` (`master` by default) as you want. If you want further
 105 customization, see [Travis CI's documentation page](https://docs.travis-ci.com/user/deployment/pages/).
 106
 107 You'll see there's `github-token: $GITHUB_TOKEN`, and this is what you should
 108 configure. Go to your [personal access tokens](https://github.com/settings/tokens)
 109 page, and generate new token with `public_repo` or `repo` permission as you
 110 need. Then go to Travis CI's settings page of your repository, and add a new
 111 environment variable `GITHUB_TOKEN` with the value of the token you generated.
 112
 113 ## Usage
 114
 115 ### Customization
 116
 117 To override the default structure and style of whiteglass, simply create the
 118 concerned directory at the root of your site, copy the file you wish to
 119 customize to that directory, and then edit the file. e.g., to override the
 120 [`_includes/footer_content.html`](_includes/footer_content.html) file to add
 121 contents to footer, create an `_includes` directory, copy
 122 `_includes/footer_content.html` from jekyll-whiteglass gem folder to
 123 `<your-site>/_includes` and start editing that file.
 124
 125 For example, you can add favicons to `_includes/head_custom.html`:
 126
 127 ``` html
 128 <link rel="icon" type="image/x-icon" href="{{ "/favicon.ico" | relative_url }}">
 129 <link rel="apple-touch-icon" href="{{ "/apple-touch-icon.png" | relative_url }}">
 130 <link rel="apple-touch-icon" sizes="76x76" href="{{ "/apple-touch-icon-76x76.png" | relative_url }}">
 131 <link rel="apple-touch-icon" sizes="120x120" href="{{ "/apple-touch-icon-120x120.png" | relative_url }}">
 132 <link rel="apple-touch-icon" sizes="152x152" href="{{ "/apple-touch-icon-152x152.png" | relative_url }}">
 133 <link rel="apple-touch-icon" sizes="180x180" href="{{ "/apple-touch-icon-180x180.png" | relative_url }}">
 134 ```
 135
 136 The site's default CSS is in the gem itself,
 137 [`assets/main.scss`](assets/main.scss). To override the default CSS, the file
 138 has to exist at your site source. Do either of the following:
 139
 140 - Create a new instance of `main.scss` at site source
 141   - Create a new file `main.scss` at `<your-site>/assets/`
 142   - Add the frontmatter dashes, and
 143   - Add `@import "whiteglass";`, to `<your-site>/assets/main.scss`
 144   - Add your custom CSS
 145 - Download the file from this repo
 146   - Create a new file `main.scss` at `<your-site>/assets/`
 147   - Copy the contents at [`assets/main.scss`](assets/main.scss) onto the `main.scss` you just created, and edit away
 148 - Copy directly from jekyll-whiteglass gem
 149   - Go to your local jekyll-whiteglass gem installation directory (run `bundle show jekyll-whiteglass` to get the path to it)
 150   - Copy the `assets/` folder from there into the root of `<your-site>`
 151   - Change whatever values you want, inside `<your-site>/assets/main.scss`
 152
 153 ### Locale
 154
 155 `site.lang` is used to declare the primary language for each web page within the
 156 site.
 157
 158 `lang: en-US` sets the `lang` attribute for the site to the United States flavor
 159 of English, while `en-GB` would be for the United Kingdom style of English.
 160 Country codes are optional and the shorter variation `lang: en` is also
 161 acceptable. You may want to write a post in different language, then add `lang`
 162 attribute to the frontmatter of that post:
 163
 164 ``` yaml
 165 layout: post
 166 title: "안녕하세요"
 167 lang: ko
 168 ```
 169
 170 ### Description
 171
 172 `site.description` describes the site. This is mainly used in meta descriptions
 173 for improving SEO. Also, you can set `description` attribute for each post:
 174
 175 ``` yaml
 176 layout: post
 177 title: Awesome Post
 178 description: This is an awesome post.
 179 ```
 180
 181 If you don't specify `post.description`, then `post.excerpt` will be used if it
 182 exist.
 183
 184 ### External URL
 185
 186 `external-url` turns the title of your post to a link. Specify a URL which you
 187 want to link to.
 188
 189 ``` yaml
 190 layout: post
 191 title: Jekyll whiteglass theme
 192 external-url: https://github.com/yous/whiteglass
 193 ```
 194
 195 Then the title of your post would look like a link with text
 196 `Jekyll whiteglass theme →`. This also applies to your blog feed.
 197
 198 ### Category
 199
 200 Each post can have `categories` attribute. It can be a string or an array. This
 201 will be displayed on index, archive and each post, and provide a link to the
 202 archive of category.
 203
 204 ``` yaml
 205 layout: post
 206 title: Awesome Post
 207 categories: Misc
 208 ```
 209
 210 ``` yaml
 211 layout: post
 212 title: Another Awesome Post
 213 categories:
 214   - Misc
 215   - Idea
 216 ```
 217
 218 ### Tag
 219
 220 Each post can have `tags` attribute. It can be a string or an array. This will
 221 be displayed on index, archive and each post, and provide a link to the archive
 222 of tag.
 223
 224 ``` yaml
 225 layout: post
 226 title: Awesome Post
 227 tags: food
 228 ```
 229
 230 ``` yaml
 231 layout: post
 232 title: Another Awesome Post
 233 tags:
 234   - food
 235   - trip
 236 ```
 237
 238 ### Feed
 239
 240 Create `<your-site>/feed.xml` with:
 241
 242 ``` yaml
 243 ---
 244 layout: feed
 245 ---
 246 ```
 247
 248 If you want to use another path for feed, you can specify a non-default path via
 249 your site's config.
 250
 251 ``` yaml
 252 feed:
 253   path: atom.xml
 254 ```
 255
 256 Then create `<your-site>/atom.xml` with the same content of `feed.xml` above.
 257
 258 ### Comments
 259
 260 whiteglass provides the ability to include your favourite commenting service, like [Disqus](https://disqus.com) or [Isso](https://posativ.org/isso).
 261
 262 To enable comments on pages and posts:
 263 1. Overwrite the `_includes/custom_comments_provider.html` with your custom provider of comments.
 264 2. Add `comments: true` to your `_config.yml`.
 265
 266 To disable comments on certain pages or posts specify `comments: false` in the front matter of the page or post.
 267
 268 ### Metadata for SEO
 269
 270 #### Keywords
 271
 272 Each post can have `keywords` attribute. This is a comma-separated list which is
 273 used in meta descriptions for improving SEO.
 274
 275 ``` yaml
 276 layout: post
 277 title: How to configure jekyll-whiteglass
 278 keywords: jekyll, whiteglass, github pages
 279 ```
 280
 281 YAML list is also available:
 282
 283 ``` yaml
 284 keywords:
 285   - jekyll
 286   - whiteglass
 287   - github pages
 288 ```
 289
 290 #### Twitter
 291
 292 - `site.twitter_username` sets `twitter:site` and `twitter:creator` meta tag
 293 - `site.twitter_image` sets `twitter:image:src` meta tag
 294 - `page.twitter_card.type` sets `twitter:card` meta tag (default: `summary`)
 295   - If `page.twitter_card.type` is `gallery`, it sets `twitter:image0`, `twitter:image1`, `twitter:image2` and `twitter:image3` meta tags with `page.twitter_card.image`, `page.twitter_card.image1`, `page.twitter_card.image2` and `page.twitter_card.image3`, respectively
 296   - If `page.twitter_card.type` is `photo`, `page.twitter_card.width` sets `twitter:image:width` meta tag and `page.twitter_card.height` sets `twitter:image:height` meta tag
 297 - `page.twitter_card.creator` sets `twitter:creator` meta tag. It overrides `site.twitter_username`
 298 - `page.twitter_card.image` sets `twitter:image:src` meta tag if `page.twitter_card.type` is not `gallery`. It overrides `site.twitter_image`
 299
 300 #### Facebook
 301
 302 - `site.facebook_app_id` sets `fb:admins` meta tag
 303 - `site.facebook_page` sets `article:author` meta tag
 304 - `site.facebook_image` sets `og:image` meta tag
 305 - `page.facebook.image` sets `og:image` meta tag. It overrides `site.facebook_image`
 306
 307 ### Navigation
 308
 309 To define header links, add titles and URLs under the `main` key in
 310 `_data/navigation.yml`:
 311
 312 ``` yaml
 313 main:
 314   - title: "About"
 315     url: /about/
 316   - title: "Archives"
 317     url: /archives/
 318   - title: "GitHub"
 319     url: https://github.com/yous/whiteglass
 320 ```
 321
 322 ### Enabling Google Analytics
 323
 324 To enable Google Analytics, add the following lines to your Jekyll site:
 325
 326 ``` yaml
 327 google_analytics: UA-NNNNNNNN-N
 328 ```