38 |
39 | [](https://github.com/MichaelCurrin/jekyll-blog-demo/generate "Use this template")
40 |
41 |
42 |
43 | Then customize the config with your own `url` and `baseurl` values. And follow docs below to install and run.
44 |
45 |
46 | ## Documentation
47 |
48 |
49 |
50 | [](/docs/ "Go to docs")
51 |
52 |
53 |
54 |
55 | ## License
56 |
57 | Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).
58 |
--------------------------------------------------------------------------------
/_config.yml:
--------------------------------------------------------------------------------
1 | ### Site metadata
2 |
3 | # Don't make the title longer than this, otherwise it gets covered in mobile view.
4 | title: Jekyll Blog Demo
5 | description: Starter for a static website or blog - built with Jekyll, a minimal theme and GH Pages
6 |
7 | email:
8 | twitter_username:
9 | github_username: MichaelCurrin
10 | rss: RSS
11 |
12 | ### Build settings
13 |
14 | url: https://michaelcurrin.github.io
15 | baseurl: /jekyll-blog-demo
16 |
17 | permalink: pretty
18 |
19 | theme: minima
20 |
21 | plugins:
22 | - jekyll-feed
23 | - jekyll-sitemap
24 |
25 | collections:
26 | tools:
27 | output: true
28 | languages:
29 | output: true
30 |
31 | defaults:
32 | - scope:
33 | path: ""
34 | values:
35 | layout: page
36 |
37 | exclude:
38 | - docs/
39 | - vendor/
40 | - Gemfile # Gemfile.lock is implied because of how matching works.
41 | - LICENSE
42 | - Makefile
43 | - README.md
44 | - sample*.png
45 |
46 | liquid:
47 | error_mode: strict
48 |
49 | strict_front_matter: true
50 |
--------------------------------------------------------------------------------
/_includes/collections-overview.html:
--------------------------------------------------------------------------------
1 |
11 |
12 |
13 | {{ content }}
14 |
15 |
16 |
17 |
18 |
19 | {%- include footer.html -%}
20 | {% include github-corner.html %}
21 |
22 |
23 |
24 |
25 |
--------------------------------------------------------------------------------
/_posts/2018-12-18-welcome-to-jekyll.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Welcome to Jekyll!"
3 | # Optional - date will be used from filename if not set here.
4 | date: 2018-12-18 18:24:52 +0200
5 | categories: jekyll update
6 | layout: post
7 | ---
8 |
9 | You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.
10 |
11 | To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.
12 |
13 | Jekyll also offers powerful support for code snippets.
14 |
15 | Using backticks.
16 |
17 | ```ruby
18 | def print_hi(name)
19 | puts "Hi, #{name}"
20 | end
21 | print_hi('Tom')
22 | #=> prints 'Hi, Tom' to STDOUT.
23 | ```
24 |
25 | Using `highlight`.
26 |
27 | {% highlight ruby %}
28 | def print_hi(name)
29 | puts "Hi, #{name}"
30 | end
31 | print_hi('Tom')
32 | #=> prints 'Hi, Tom' to STDOUT.
33 | {% endhighlight %}
34 |
35 | Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk].
36 |
37 | [jekyll-docs]: https://jekyllrb.com/docs/home
38 | [jekyll-gh]: https://github.com/jekyll/jekyll
39 | [jekyll-talk]: https://talk.jekyllrb.com/
40 |
--------------------------------------------------------------------------------
/_posts/2018-12-22-first-post.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "First post!"
3 | layout: post
4 | ---
5 | This is my first post after the one created as part of the blog template.
6 |
--------------------------------------------------------------------------------
/_tools/github-pages.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: GitHub Pages
3 | description: |+
4 | Websites for you and your projects.
5 |
6 | Hosted directly from your GitHub repository. Just edit, push, and your changes are live.
7 | ---
8 |
9 | See the [pages.github.com](https://pages.github.com/) home to learn more.
10 |
11 | With the standard flow, you don't need to run any CI steps yourself, locally or on GitHub. Just setup a repo that matches the minimum structure like this - [MichaelCurrin/simplest-jekyll](https://github.com/MichaelCurrin/simplest-jekyll).
12 |
13 | Then whenever you commit on GitHub or push to GitHub from your machine, then GitHub will build and deploy your site.
14 |
15 |
16 | ## Limitations
17 |
18 | Note the limitation that only certain Ruby gems are allowed and with locked versions. This limits the themes and plugins you can use. But there are plenty to use and a typical blog this be fine.
19 |
20 | See [GitHub Pages Versions](https://pages.github.com/versions/)
21 |
22 | When it comes to using themes, you can also use the Remote Themes plugin to pull in any theme from a GitHub URL, even if it is not on the standard gems list.
23 |
24 |
25 | ## Extending your build flow
26 |
27 | If you end up wanting more complex build flows with your own build and CI steps or custom gems, then consider using GitHub Actions for your GH Pages site. Or [Netlify](https://netlify.com/) - which is a separate platform that integrates well with a GitHub repo and has a config of just a few lines. Unlike GitHub Pages which needs longer setup.
28 |
--------------------------------------------------------------------------------
/_tools/jekyll.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Jekyll
3 | description: Transform your plain text into static websites and blogs.
4 | ---
5 |
6 | A fun and easy static-site generator.
7 |
8 | Read more on the [jekyllrb.com](https://jekyllrb.com/) homepage.
9 |
--------------------------------------------------------------------------------
/_tools/ruby.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Ruby
3 | description: |
4 | A dynamic, open source programming language with a focus on simplicity
5 | and productivity. It has an elegant syntax that is natural to read and easy to write.
6 | ---
7 |
8 | Read more on the [ruby-lang.org](https://www.ruby-lang.org/en/) homepage.
9 |
10 | Recommended - using Ruby 2.6 and Ruby 2.7 for a Jekyll site. Ruby 3 has been released but is not compatible yet.
11 |
--------------------------------------------------------------------------------
/about.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: About
3 | layout: page
4 | permalink: /about/
5 | ---
6 |
7 | This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/)
8 |
9 | Source code:
10 |
11 | [](https://github.com/jekyll/jekyll)
12 |
13 | [](https://github.com/jekyll/minima)
14 |
--------------------------------------------------------------------------------
/assets/main.scss:
--------------------------------------------------------------------------------
1 | ---
2 | ---
3 |
4 | @import "minima";
5 |
6 | @media screen and (max-width: 900px) {
7 | .site-nav {
8 | position: absolute;
9 | right: 90px;
10 | }
11 | }
12 |
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
1 | # Jekyll Blog Demo documentation
2 |
3 | - [Installation](installation.md)
4 | - [Usage](usage.md)
5 | - [Template notes](template-notes/)
6 |
7 |
--------------------------------------------------------------------------------
/docs/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | Set up this project to run locally. On Linux, macOS or Windows.
4 |
5 |
6 | ## Requirements
7 |
8 | - _Ruby_ - To install the project-scoped gems, including Jekyll.
9 | - _Bundler_ - Used to manage Ruby gem dependencies in an isolated directory, to preserve your global gems.
10 | - _Make_ - The docs here use the _make_ command, which comes standard on macOS or Linux machine, but on Windows you need to download and install Make. Or, if you go to [Makefile](/Makefile), you can look up the appropriate shell commands to run without `make`.
11 |
12 |
13 | ## Clone
14 |
15 | Optionally add this to your own repos - either fork this repo or click _Use this Template_.
16 |
17 | Then clone your repo or this one.
18 |
19 | Navigate to the repo root directory locally.
20 |
21 | You can view the commands available in the [Makefile](/Makefile) or skip to the next step. Note that `make` only works in macOS or Linux. Thought, it is optional, as you can run commands directly
22 |
23 | ```sh
24 | $ make help
25 | ```
26 |
27 |
28 | ## Install system dependencies
29 |
30 | Install Ruby and Bundler globally - follow this [gist](https://gist.github.com/fb758aea4d35e03b9ed093afddf4e7ec).
31 |
32 |
33 | ## Install project dependencies
34 |
35 | Install local gems.
36 |
37 | ```sh
38 | $ make install
39 | ```
40 |
41 |
42 | ## Upgrade
43 |
44 | Run this command if needed upgrade to the latest gems.
45 |
46 | ```sh
47 | $ make upgrade
48 | ```
49 |
50 | When you upgrade, the `Gemfile.lock` file will be updated, if there are any changes. You can commit this to your own repo. This file is optional for _GitHub Pages_.
51 |
--------------------------------------------------------------------------------
/docs/template-notes/README.md:
--------------------------------------------------------------------------------
1 | # Template notes
2 |
3 |
4 |
5 | This project was generated using the Jekyll CLI for a starting point.
6 |
7 | Now it also includes a demo of Jekyll _Collections_ too. See the _Languages_ section on the site, the `languages.md` file and the `_languages` directory.
8 |
--------------------------------------------------------------------------------
/docs/template-notes/about.md:
--------------------------------------------------------------------------------
1 | # About
2 |
3 |
4 | ## Purpose
5 |
6 | This project serves as a starting point or a reference for building a statically-generated website using [Jekyll](https://jekyllrb.com/) and includes enough content and styling to demonstrate what a themed multi-page blog looks like, while the structure is easy to understand by keeping the number of files and lines of code low.
7 |
8 | Run this project as a local web server or remotely such as on [GitHub Pages](https://pages.github.com/) or Netlify.
9 |
10 | Only a simple repo configuration change is needed after you use this template - see the [GitHub Pages tutorial](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) in GitHub's docs.
11 |
12 | _Note: This project's are instructions intended for a Linux or macOS environment._
13 |
14 | Beginner tip for [Gemfile](/Gemfile) - this Gemfile is only used when running Jekyll locally i.e. it is **ignored** by GitHub Pages. It is useful when doing a GH Actions or Netlify build though.
15 |
16 | Versions should match GH Pages versions - [pages.github.com/versions/](https://pages.github.com/versions/).
17 |
18 |
19 | ## Demo site
20 |
21 | Through setting GitHub Pages section of the Github repo's settings, this site is available at:
22 |
23 | - [michaelcurrin.github.io/jekyll-blog-demo](https://michaelcurrin.github.io/jekyll-blog-demo/)
24 |
25 | Since this is a _project_ site and note a _user_ site, the subpath of `jekyll-blog-demo` is automatically set using the repo's name. In order to keep navigation and asset URLs in line with this and prevent errors, the `baseurl` in the [config](/_config.yml) file is also set to that subpath.
26 |
27 |
28 | # Project structure
29 |
30 | This project follows the typical structure of a Jekyll-based site.
31 |
32 | - The main content pages are markdown and HTML files at the top-level directory. See [index.md](/index.md) and [about.md](./about.md). Blog posts are in the [_posts](/_posts) directory.
33 | - The pages use "layout" fields to point to template files for styling and structure. There are no layouts in this project as the theme's layouts are referenced though.
34 | - The [minima](https://github.com/jekyll/minima) Jekyll theme is used for styling. This means that little or HTML is need in the content files from the first point above.
35 | - Jekyll builds to a `_site` directory both locally and on Github Pages. That directory contains public content that is served from the site's root URL. Certain files are not copied there based on Jekyll's rules and you can also added to the `excludes` field in the config. This prevents templates, the license and other private files from being served on the site.
36 | - This tutorial on Jekyll docs covers a few pages and posts. I've extended to include a collection too.
37 |
--------------------------------------------------------------------------------
/docs/template-notes/background.md:
--------------------------------------------------------------------------------
1 | # Background
2 |
3 |
4 | ## About static sites and Jekyll
5 |
6 | The Github Page service lets you build and serve a statically generated site.
7 |
8 | The most basic way is to serve some flat HTML files (and other assets) without any logic. This is great for a one-page site with custom styling (rather than using a theme).
9 |
10 | This project is more advanced and runs with Jekyll. This is done by adding a [\_config.yml](/_config.yml) file. This lets you use templating and themes, which makes it easier to avoid code duplication and lets you change out a theme in your config rather than your content files. Read more in this [config guide](https://github.com/MichaelCurrin/code-cookbook/blob/master/recipes/jekyll/project-files/config.md).
11 |
12 | Note that the [Gemfile](/Gemfile) is used for local development and not used by Github Pages.
13 |
14 |
15 | ## Simple site
16 |
17 | A basic Jekyll site with theme can be made using files as follows:
18 |
19 | - **index.md** - The website homepage, including which layout to use and some body content.
20 | ```markdown
21 | ---
22 | layout: home
23 | ---
24 |
25 | Hello, world!
26 |
27 | More content goes here. Markdown is valid here. Make sure it is not indented otherwise at 4 spaces it becomes a codeblock.
28 |
29 | 
21 |
22 | 
20 |
21 |