Repository: jsanz/gh-pages-minima-starter Branch: master Commit: ffe3ac0cbe20 Files: 21 Total size: 16.1 KB Directory structure: gitextract_kf24lx0h/ ├── .gitignore ├── Dockerfile ├── Gemfile ├── LICENSE ├── README.md ├── _config.yml ├── _includes/ │ └── footer.html ├── _pages/ │ ├── 404.md │ ├── about.md │ ├── archive.md │ └── frontpage.md ├── _posts/ │ ├── 2020-03-18-my-first-post.md │ ├── 2020-03-22-get-code.md │ ├── 2020-03-24-edit-content.md │ ├── 2020-03-25-github-edit.md │ ├── 2020-04-15-posts.md │ ├── 2020-04-17-local-env.md │ ├── 2020-04-19-links.md │ └── 2020-04-20-html.md ├── assets/ │ └── main.scss └── docker-compose.yml ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ _site/ .sass-cache/ .jekyll-cache/ .jekyll-metadata .vscode **/*.swp env ================================================ FILE: Dockerfile ================================================ # Create a Jekyll container from a Ruby Alpine image # At a minimum, use Ruby 2.5 or later FROM ruby:2.7-alpine3.15 WORKDIR /srv/jekyll # Add Jekyll dependencies to Alpine RUN apk update RUN apk add --no-cache build-base gcc cmake git COPY ./Gemfile* /srv/jekyll # Update the Ruby bundler and install Jekyll RUN gem update bundler && bundle install ================================================ FILE: Gemfile ================================================ source "https://rubygems.org" gem 'github-pages', group: :jekyll_plugins gem "webrick", "~> 1.8" ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2020 Jorge Sanz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # gh-pages-minima-starter This is a template and some instructions for running Github Pages with the [`minima` theme][minima]. This repo has what I consider the minimum pieces for a personal blog using [Jekyll][jk] and [Github Pages][gh-site]: * Frontpage that includes your last blog posts: `_pages/frontpage.md` * Archive for all your posts: `_pages/archive.md` * About page: `_pages/about.md` * Minimum 404 page: `_pages/404.md` * Minimum metadata in the `_config.yml` * Example CSS change inside `assets/main.scss` * Custom footer template `_includes/footer.html` Check out the excellent [`minima` theme][minima] documentation for further details and customization and the [official docs][gh] for more details on how Github Pages work. For more details on how to set it up locally, create content, use Github interface, etc. feel free to visit this [website post][dev] or the source code here. Do you have questions? feel free to [open an issue](https://github.com/jsanz/gh-pages-minima-starter/issues/new/choose) or [contact me](https://jorgesanz.net/contact). Enjoy!! [gh-site]: https://pages.github.com/ [jk]: https://jekyllrb.com/ [minima]: https://github.com/jekyll/minima/tree/2.5-stable [gh]: https://help.github.com/en/github/working-with-github-pages [gh-settings]: https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site [dev]: https://jsanz.github.io/gh-pages-minima-starter/2020/04/17/local-env.html ================================================ FILE: _config.yml ================================================ title: My blog description: My very nice blog author: "Jorge Sanz" theme: minima base_url: /gh-pages-minima-starter repository: jsanz/gh-pages-minima-starter # Minima social links github_username: jsanz linkedin_username: jsanz rss: rss # Minima: show excerpts in the frontpage show_excerpts: true minima: date_format: "%Y-%m-%d" # Minima: custom header links header_pages: - _pages/frontpage.md - _pages/about.md - _pages/archive.md include: - _pages exclude: - .gitignore - docker-compose.yml - Gemfile - Gemfile.lock - LICENSE - README.md ================================================ FILE: _includes/footer.html ================================================ ================================================ FILE: _pages/404.md ================================================ --- permalink: /404 layout: page title: Ooops! --- That url does not exist, sorry!! ================================================ FILE: _pages/about.md ================================================ --- permalink: /about layout: page title: About me --- More details about me on this page with links to my social media profiles and so on. ![](https://www.jorgesanz.net/assets/imgs/me/jsanz_small4.png) ================================================ FILE: _pages/archive.md ================================================ --- permalink: /archive layout: page title: Blog archive --- ================================================ FILE: _pages/frontpage.md ================================================ --- permalink: / layout: home title: Welcome list_title: My blog posts --- This is a template and some instructions for running Github Pages with the [`minima` theme][minima]. This repo has what I consider the minimum pieces for a personal blog using [Jekyll][jk] and [Github Pages][gh-site]. Check out the excellent [`minima` theme][minima] documentation for further details and customization and the [official docs][gh] for more details on how Github Pages work. Do you have questions? feel free to [open an issue][issue] or find out how toreach me from my [contact page][contact]. For more details about how this example site works checkout [the github project](https://github.com/jsanz/gh-pages-minima-starter). Have a great day!! [gh-site]: https://pages.github.com/ [minima]: https://github.com/jekyll/minima/tree/2.5-stable [jk]: https://jekyllrb.com/ [gh]: https://help.github.com/en/github/working-with-github-pages [issue]: https://github.com/jsanz/gh-pages-minima-starter/issues/new/choose [contact]: https://jorgesanz.net/contact/ ================================================ FILE: _posts/2020-03-18-my-first-post.md ================================================ --- title: "Tutorial I: my first post" date: 2020-03-18 layout: post --- This is **my very first post**!! I can write * unnumbered * fancy * lists But also 1. numbered 1. ones 1. easily Images ![a gif!](https://media.giphy.com/media/l0MYt5jPR6QX5pnqM/giphy.gif) And so on... ================================================ FILE: _posts/2020-03-22-get-code.md ================================================ --- title: "Tutorial II: Take the code!" date: 2020-03-22 layout: post --- How to use this template? Well the easiest way may be to hit the **"Use this template"** green button on the [Github repository](https://github.com/jsanz/gh-pages-minima-starter) page to copy the repository structure into your own account. You can have your website **without setting up a local environment** (but [you can do it]({{ site.baseurl }}{% post_url 2020-04-17-local-env %}) if you are a bit tech savvy). After creating the project, the first thing I would do is to change the project name at the `Settings` tab. The name of the project will became part of the website main address. So if for example you name your repo as `myblog`, your website will be available at `https://yourusername.github.io/myblog`. There is a special case, if you name your repo as `yourusername.github.io` then the website will be published at `https://yourusername.github.io` which may be a good idea for a personal website! Next thing to do is to customize the main settings on the `_config.yml` file: website title, description, base URL (remove this setting it if you are deploying to your GitHub user website), and your details. If you don't want to show excerpts of your posts in the front page you can disable that checking removing that entry on adding a `#` at the beginning of that line. You don't need to change anything else. After the configuration is ready you can enable the website publishing on the same `Settings` page a bit further down. Remember to set up the `master` branch as the source of your documents. Once you save your settings wait for a few minutes and your site is ready!! Any time you change anything in your repository you do an operation called _pushing a commit_. On every push the website is rebuilt. You can see the details of that process in the `Environment` section that is accessible from the repository front-page. ![](./assets/imgs/environments.png) ================================================ FILE: _posts/2020-03-24-edit-content.md ================================================ --- title: "Tutorial III: editing your content" date: 2020-03-24 layout: post --- From the [last post]({{ site.base_url }}{% link _posts/2020-03-22-get-code.md %}), your website is published with your details but now how to edit the frontpage, remove the example blog posts or create your own. Let's dive in to that. First thing to know is that [Github Pages](https://pages.github.com/) by default accepts rendering content in HTML and [Markdown](https://daringfireball.net/projects/markdown/syntax). I **strongly** recommend using Markdown because it's very simple and out of your way when you write, since the formatting rules are very simple. If you are going to write a long piece, you may want to use an external editor and then upload or paste your content into github. There are many text editors that support Markdown but if I have to suggest one that works well for writing I'd go for [typora](https://typora.io/) because it's supporting Linux, Windows, and also MacOS (in beta).
_Typora_ ================================================ FILE: _posts/2020-03-25-github-edit.md ================================================ --- title: "Tutorial IV: editing from Github" date: 2020-03-25 layout: post --- Editing pages in Github is **super simple**, just click on the pencil in the top right corner and open an editing interface where you can even preview the changes that you are applying. Once you are done add a short comment to your change (_commit_ in git/github vocabulary) and save them. Remember all changes are saved and available for you to explore afterwards if needed. ![]({{ site.base_url }}{% link /assets/imgs/editing.gif %}) If your site grows you may want to set up a local environment to make things easier to you. We cover that in the [local environment]({% link _posts/2020-04-15-posts.md %}) post. ================================================ FILE: _posts/2020-04-15-posts.md ================================================ --- title: "Tutorial V: posts" date: 2020-4-15 layout: post --- Posts in your website are stored in the `_posts` folder and they follow a naming convention that you should follow using the date first (year, month, day) and then a simple title slug. This helps to keep things organized. If you are using Github interface, you can use the top right buttons to create new files or upload them. ![]({{ site.base_url }}{% link /assets/imgs/files.png %}) Find more details on how to write Jekyll posts on [the docs](https://jekyllrb.com/docs/posts/). ================================================ FILE: _posts/2020-04-17-local-env.md ================================================ --- title: "Tutorial VI: local environment" date: 2020-4-17 layout: post --- I've included a simple `docker-compose.yml` file in the root of the repo, so you can spin up a local environment without having to install in your computer Ruby or any other library. If you are versed in `Ruby`, `gems`, and `bundle` you can probably skip this section and go ahead! Just install [Docker][docker] and [Docker Compose][compose], visit the repo folder and run `docker compose build`. Then, every time you wan to spin up the local environment just run `docker compose up` and visit `http://localhost:8080/gh-pages-minima-starter`. Alternatively, if you prefer to install all the software locally please follow the [docs][install]. The compose file is super simple, it just refers to a local `Dockerfile` image definition setting up the current folder as the container `/srv/jekyll` directory and starts the server with convenient options like livereload. ```yaml version: '3' services: jekyll: build: context: . command: jekyll serve --watch --force_polling --incremental --port 8080 -H 0.0.0.0 --livereload --livereload-port 35729 --baseurl /gh-pages-minima-starter volumes: - .:/srv/jekyll ports: - '8080:8080' - '35729:35729' environment: RUBYOPT: '-W0' JEKYLL_ENV: production ``` [install]: https://help.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll [docker]: https://docs.docker.com/get-docker/ [compose]: https://docs.docker.com/compose/ ================================================ FILE: _posts/2020-04-19-links.md ================================================ --- title: "Tutorial VII: internal links" date: 2020-04-19 layout: post --- In your blog post you will write links to internal resources, like other articles, pages, and images. You can use relative paths for those assets so for example to link the archive you may use the following code `[archive](/archive)`. This will work fine, since that's the url of your archive, but what happens if you decide to change the url? You'd have to search for any occurrence in your site for any link and fix it. A different approach is to use a Jekyll feature called *Liquid tags*. From the [documentation](https://jekyllrb.com/docs/liquid/): > Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language to process templates. > > Generally in Liquid you output content using two curly braces e.g. `{% raw %}{{ variable }}{% endraw %}` and perform logic statements by surrounding them in a curly brace percentage sign e.g. `{% raw %}{% if statement %}{% endraw %}`. To learn more about Liquid, check out the [official Liquid Documentation](https://shopify.github.io/liquid/). There is a Liquid tag to link to files, getting as a result the corresponding url for the resource. So for our archive we would use: ```{% raw %} [archive]({{ site.base_url }}{% link _pages/archive.md %}) {% endraw %}``` and this would be automatically converted into ``` [archive]({{ site.base_url }}{% link _pages/archive.md %}) ``` For a blog post this: ```{% raw %} [first post]({{ site.base_url }}{% link _posts/2020-03-18-my-first-post.md %}) {% endraw %}``` transforms into: ``` [first post]({{ site.base_url }}{% link _posts/2020-03-18-my-first-post.md %}) ``` Apart from the benefit of being resilient to changes in the permalinks of your articles, this also has a very important effect: Jekyll **will fail** to process your site if you use a wrong link. This means that Jekyll checks your internal links on every built, and if for any reason you change the name of your file in the future, Jekyll will error with details on where the offending link lives. An important final note is that if you paid attention, the links are relative to the root of your domain. If you deploy this site in your personal GitHub space that's OK but if you publish it in a project so your URL is like `https://yourusername.github.io/project` then the URLs will fail. You'd need to put `{% raw %}{{ site.base_url }}{% endraw %}` **before** the `link` tag, for absolute URLs that point to the correct resource. More details on this [nice article](https://www.webisland.agency/blog/jekyll-internal-links/). ================================================ FILE: _posts/2020-04-20-html.md ================================================ --- title: "Tutorial VIII: HTML" date: 2020-04-20 layout: post --- Quick note on highlighting that Markdown supports raw HTML. That means that if for some reason Markdown falls short or becomes inconvenient for a thing you are authoring, you can always use HTML as a fallback solution. One very common scenario is customizing the width and height of your images. You can check the source code of the [editing content]({% link _posts/2020-03-24-edit-content.md %}) post to see how I moved from the standard syntax for images using `![alt text](image path)` to use HTML to allow to set up a custom width using a CSS style. ```html{% raw %}

Another example could be to change text color.

{% endraw %}```

Another example could be to change text color.

Easy right? 😀 ================================================ FILE: assets/main.scss ================================================ --- --- @import "minima"; @import url('https://fonts.googleapis.com/css?family=Montserrat&display=swap'); body { font-family: 'Montserrat', sans-serif; color: #383838; } ================================================ FILE: docker-compose.yml ================================================ version: '3' services: jekyll: build: context: . command: jekyll serve --watch --force_polling --incremental --port 8080 -H 0.0.0.0 --livereload --livereload-port 35729 --baseurl /gh-pages-minima-starter volumes: - .:/srv/jekyll ports: - '8080:8080' - '35729:35729' environment: RUBYOPT: '-W0' JEKYLL_ENV: production