OCram85
/
beautifulSA-jekyll
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity
beautifulSA-jekyll/docs/getstarted.md

5.8 KiB
Raw Blame History

layout title subtitle bigimg css
page Getting started How to use Beautiful Jekyll /assets/img/start.jpg /assets/css/demo.css

Beautiful Jekyll is a ready-to-use template to make help you create an awesome Jekyll or GitHub Pages website quickly.

To learn how you can use Beautiful Jekyll to create your website in minutes, go to the Beautiful Jekyll project page.


Installation steps (recommended way)

There are only three simple steps, so using Beautiful Jekyll is literally as easy as 1-2-3 :)

Here is a 40-second video showing how to get started, with the specific steps below. For a more complete installation guide, visit the Beautiful Jekyll page.

Installation steps

1. Fork (copy) the Beautiful Jekyll project

2. Rename the project to yourusername.github.io

3. Customize settings in the config.yml file to personalize your website

That's it! You can now visit your shiny new website.

See how easy that is? I wasn't lying - it really can be done in two minutes.



Installation steps (as a ruby gem - the hard way)

For most people (including myself!), I suggest using the easy way and ignoring this section. If you're an advanced user and want to use beautiful-jekyll as a ruby gem, then follow these steps.

Beautiful-Jekyll was initially developed as a GitHub Pages theme that was meant to be used via forking as described above, but due to high demand it's now also available as a Github "remote_theme" and as a Ruby Gem.

There are three other ways of using beautiful-jekyll. These are advanced uses and you should only use one of these methods if you know how to write jekyll sites from scratch. You should look up the official documentation for whichever method you want to use, but here are the basics:

  • Method 1: Using remote_theme with a GitHub repository

    • Create a new GitHub repository or go to an existing repository
    • Add remote_theme: daattali/beautiful-jekyll@2.1.0 to your _config.yml file (make sure to remove any previous theme or remote_theme parameters that may have been there before)
    • Go to Settings, scroll down to the GitHub Pages section, and choose "master branch" as the source
    • Your website will be at https://<yourusername>.github.io\<projectname>

  • Method 2: Using remote_theme with a Ruby Jekyll site

    • Install Ruby and Jekyll (sudo apt-get install ruby ruby-dev make gcc and sudo gem install jekyll bundler)
    • Create a new jekyll site (e.g. jekyll new mysite)
    • Add gem "jekyll-remote-theme" to your Gemfile and then run bundle install to install the plugin
    • Add remote_theme: daattali/beautiful-jekyll@2.1.0 to your _config.yml file (make sure to remove any previous theme or remote_theme parameters that may have been there before)
    • Add - jekyll-remote-theme to the plugins section of your _config.yml file to activate the plugin

  • Method 3: Using the Beautiful-Jekyll theme gem

    • Install Ruby and Jekyll (sudo apt-get install ruby ruby-dev make gcc and sudo gem install jekyll bundler)
    • Create a new jekyll site (e.g. jekyll new mysite)
    • Add gem "beautiful-jekyll-theme", "2.1.0" to your Gemfile
    • Add theme: beautiful-jekyll-theme to your _config.yml
    • Run bundle

If you're developing using a local ruby gem (as opposed to on GitHub), you can preview your site by running bundle exec jekyll serve (optionally with -H 0.0.0.0 if needed).

When you use beautiful-jekyll with the "easy way", you'll have direct access to all the theme's files because you'll be literally copying the project. But if you use one of these three "hard" methods, many of the theme's files and folders will be hidden from you, so you'll need to:

  • Go through beautiful-jekyll's _config.yml file and copy any settings you want to use into your project's config file.
  • Some config features will not work immediately because of missing files that you'll need to copy from beautiful-jekyll into your project
    • To enable the link-tags feature, you need to copy tags.html
    • To enable the RSS feed, copy feed.xml
    • If you use staticman comments, copy staticman.yml and _data/ui-text.yml.
  • If you want the home page to include a feed of all blog posts, create an index.html file and use layout: home in its YAML.
  • If you want to replace any file served from beautiful-jekyll (such as a CSS file, a layout, or an include), you'll need to place it with the exact same path in your own jekyll repo (e.g. /assets/css/main.css)

If at any point in the future you want to update to a newer version of beautiful-jekyll, you can come back to this page and see if there's a new version. If there is, you can simply update the remote_theme or gem fields accordingly.

After setting up your site, you still need to go through the rest of the beautiful-jekyll documentation to learn about all its features and how to use it.