demo site now mirrored in IPFS!
by Armando Maynez based on V1.0 by Artem Sheludko.
Adam Blog 2.0 is a Jekyll theme that was built to be 100% compatible with GitHub Pages. If you are unfamiliar with GitHub Pages, you can check out their documentation for more information. Jonathan McGlone's guide on creating and hosting a personal site on GitHub is also a good resource.
Jekyll is a simple, blog-aware, static site generator for personal, project, or organization sites. Basically, Jekyll takes your page content along with template files and produces a complete website. For more information, visit the official Jekyll site for their documentation. Codecademy also offers a great course on how to deploy a Jekyll site for complete beginners.
The beauty of hosting your website on GitHub is that you don't have to actually have Jekyll installed on your computer. Everything can be done through the GitHub code editor, with minimal knowledge of how to use Jekyll or the command line. All you have to do is add your posts to the _posts directory and edit the _config.yml file to change the site settings. With some rudimentary knowledge of HTML and CSS, you can even modify the site to your liking. This can all be done through the GitHub code editor, which acts like a content management system (CMS).
- SEO meta tags
- Dark mode (configurable in _config.yml file)
- automatic sitemap.xml
- automatic archive page with infinite scrolling capability
- new page of posts filtered by a single tag (without needing autopages from paginator V2), also with infinite scrolling
- click to tweet functionality (just add a
<tweet> </tweet>tag in your markdown. - custom and responsive 404 page
- responsive and automatic Table of Contents (optional per post)
- read time per post automatically calculated
- responsive post tags and social share icons (sticky or inline)
- included linkedin, reddit and bandcamp icons
- copy link to clipboard sharing option (and icon)
- view on github link button (optional per post)
- MathJax support (optional per post)
- tag cloud in the home page
- 'back to top' button
- comments 'courtain' to mask the disqus interface until the user clicks on it (configurable in _config.yml)
- CSS variables to make it easy to customize all colors and fonts
- added several themes for code syntax highlight configurable from the _config.yml file.
- responsive footer menu and footer logo (if setup in the config file)
- search shows results based on full post content, not just the description
- smoother menu animations
The main page looks like this:
Dark mode selector in main menu:
The post page looks like:
Custom responsive 404:
Dark mode looks like this:
For a full local installation of Adam Blog 2.0, download your own copy of Adam Blog 2.0 and unzip it into it's own directory. From there, open up your favorite command line tool, enter bundle install, and then enter jekyll serve. Your site should be up and running locally at http://localhost:4000.
If you're completely new to Jekyll, I recommend checking out the documentation at https://jekyllrb.com/ or there's a tutorial by Smashing Magazine.
If you are hosting your site on GitHub Pages, then committing a change to the _config.yml file (or any other file) will force a rebuild of your site with Jekyll. Any changes made should be viewable soon after. If you are hosting your site locally, then you must run jekyll serve again for the changes to take place.
Head over to the _posts directory to view all the posts that are currently on the website, and to see examples of what post files generally look like. You can simply just duplicate the template post and start adding your own content.
Fork this repository into your own account.
You can host your Jekyll site for free with Github Pages. Click here for more information.
When forking, if you use as destination a repository named USERNAME.github.io then your url will be https://USERNAME.github.io/, else https://USERNAME.github.io/REPONAME/) and your site will be published to the gh-pages branch. Note: if you are hosting several sites under the same GitHub username, then you will have to use Project Pages instead of User Pages - just change the repository name to something other than 'http://USERNAME.github.io'.
In addition to your github-username.github.io repo that maps to the root url, you can serve up sites by using a gh-pages branch for other repos so they're available at github-username.github.io/repo-name.
This will require you to modify the _config.yml like so:
# Site settings
title: Repo Name
email: [email protected]
author: Your Name
description: "Repo description"
baseurl: "/repo-name"
url: "https://github-username.github.io"This will ensure that the the correct relative path is constructed for your assets and posts.
Modify _config.yml file, located in the root directory, with your data.
# Site settings
title: The Title for Your Website
description: 'A description of your blog'
permalink: ':title:output_ext' # how the permalinks will behave
baseurl: "/" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
logo: "" # the logo for your site
logo-icon: "" # a smaller logo, typically squared
logo-icon-SEO: "" # must be a non SVG file, could be the same as the logo-icon
# Night/Dark mode default mode is "auto", "auto" is for auto nightshift (19:00 - 07:00), "manual" is for manual toggle, and "on/off" is for default on/off. Whatever the user's choice is, it will supersede the default setting of the site and be kept during the visit (session). Only the dark mode setting is "manual", it will be always kept on every visit (i.e. no matter the browser is closed or not)
night_mode: "auto"
logo-dark: "/assets/img/branding/MVM-logo-full-dark.svg" #if you want to display a different logo when in dark mode
highlight_theme: syntax-base16.monokai.dark # select a dark theme for the code highlighter if needed
# Author settings
author: Your Name # add your name
author-pic: '' # a picture of you
about-author: '' # a brief description of you
# Contact links
email: [email protected] # Add your Email address
phone: # Add your Phone number
website: # Add your website
linkedin: # Add your Linkedin handle
github: # Add your Github handle
twitter: # Add your Twitter handle
bandcamp: # Add your Bandcamp username
# Tracker
analytics: # Google Analytics tag ID
fbadmin: # Facebook ID admin
# Paginate
paginate: 6 # number of items to show in the main page
paginate_path: 'page:num'
words_per_minute: 200 # default words per minute to be considered when calculating the read time of the blog postsTo configure the newsletter, please create an account in https://mailchimp.com, set up a web signup form and paste the link from the embed signup form in the config.yml file:
# Newsletter
mailchimp: "https://github.us1.list-manage.com/subscribe/post?u=8ece198b3eb260e6838461a60&id=397d90b5f4"To configure Disqus, set up a Disqus site with the same name as your site. Then, in _config.yml, edit the disqus_identifier value to enable.
# Disqus
discus_identifier: # Add your discus identifier
comments_curtain: yes # leave empty to show the disqus embed directlyMore information on how to set up Disqus.
Customize the site colors. Modify /assets/css/main.css as follows:
html {
--shadow: rgba(32,30,30,.3);
--accent: #DB504A; /* accent */
--accent-dark: #4e3e51; /* accent 2 (dark) */
--main: #326273; /* main color */
--main-dim: #879dab; /* dimmed version of main color */
--text: #201E1E;
--grey1: #5F5E58;
--grey2: #8D897C;
--grey3: #B4B3A7;
--grey4: #DAD7D2;
--grey5: #F0EFED;
--background: #ffffff;
}
html[data-theme="dark"] {
--accent: #d14c47; /* accent */
--accent-dark: #CD8A7A; /* accent 2 (dark) */
--main: #4C6567; /* main color */
--main-dim: #273335; /* dimmed version of main color */
--text: #B4B3A7;
--grey1: #8D897C;
--grey2: #827F73;
--grey3: #76746A;
--grey4: #66645D;
--grey5: #4A4945;
--background: #201E1E;
--shadow: rgba(180,179,167,.3);
}Customize the site fonts. Modify /assets/css/main.css as follows:
...
--font1: 'Lora', charter, Georgia, Cambria, 'Times New Roman', Times, serif;/* body text */
--font2: 'Source Sans Pro', 'Helvetica Neue', Helvetica, Arial, sans-serif; /* headers and titles */
--font1-light: 400;
--font1-regular: 400;
--font1-bold: 600;
--font2-light: 200;
--font2-regular: 400;
--font2-bold: 700;
...If you change the fonts, you need to also modify /_includes/head.html as follows:
Uncomment and change the following line with your new fonts and font weights:
<link href="https://fonts.googleapis.com/css?family=Lora:400,600|Source+Sans+Pro:200,400,700" rel="stylesheet">Delete everything within <style></style> just before the line above:
<style>
/* latin */
@font-face {
font-family: 'Lora';
...
</style>You will find example posts in your /_posts/ directory. Go ahead and edit any post and re-build the site to see your changes, for github pages, this happens automatically with every commit. 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.
To add new posts, simply add a file in the _posts directory that follows the convention of YYYY-MM-DD-name-of-post.md and includes the necessary front matter. Take a look at any sample post to get an idea about how it works. If you already have a website built with Jekyll, simply copy over your posts to migrate to Adam Blog 2.0.
The front matter options for each post are:
---
layout: post #ensure this one stays like this
read_time: true # calculate and show read time based on number of words
show_date: true # show the date of the post
title: Your Blog Post Title
date: XXXX-XX-XX XX:XX:XX XXXX
description: "The description of your blog post"
img: # the path for the hero image, from the image folder (if the image is directly on the image folder, just the filename is needed)
tags: [tags, of, your, post]
author: Your Name
github: username/reponame/ # set this to show a github button on the post
toc: yes # leave empty or erase for no table of contents
---Edit your blogpost using markdown. Here is a good guide about how to use it.
Delete images inside of /assets/img/posts/ and upload your own images for your posts.
Make sure Github Pages are turned on in the repository settings, and pointing to the main or master branch (where you cloned this repo).
If you are familiar with Jekyll, then the Adam Blog 2.0 directory structure shouldn't be too difficult to navigate. The following some highlights of the differences you might notice between the default directory structure. More information on what these folders and files do can be found in the Jekyll documentation site.
Adam Blog 2.0/
├── _includes # Theme includes
├── _layouts # Theme layouts (see below for details)
├── _posts # Where all your posts will go
├── assets # Style sheets and images are found here
| ├── css # Style sheets go here
| | └── _sass # Folder containing SCSS files
| | └── main.css # Main SCSS file
| | └── highlighter # Style sheet for code syntax highlighting
| └── img #
| └── posts # Images go here
├── _pages # Website pages (that are not posts)
├── _config.yml # Site settings
├── Gemfile # Ruby Gemfile for managing Jekyll plugins
├── index.html # Home page
├── LICENSE.md # License for this theme
├── README.md # Includes all of the documentation for this theme
├── feed.xml # Generates atom file which Jekyll points to
├── 404.html # custom and responsive 404 page
├── all-posts.json # database of all posts used for infinite scroll
├── ipfs-404.html # 404 page for IPFS
├── posts-by-tag.json # database of posts by tag
├── robots.txt # SEO crawlers exclusion file
├── search.json # database of posts used for search
└── sitemap.xml # automatically generated sitemap for search enginesTo completely start from scratch, simply delete all the files in the _posts, assets/img/posts folders, and add your own content. Everything in the _config.yml file can be edited to suit your needs. Also change the favicon.ico file to your own favicon.
If you have a tweetable quote in your blog post and wish to feature it as a click to tweet block, you just have to use the <tweet></tweet> tags, everything between them will be converted in a click to tweet box.
It is possible to track your site statistics through Google Analytics. Similar to Disqus, you will have to create an account for Google Analytics, and enter the correct Google ID for your site under google-ID in the _config.yml file. More information on how to set up Google Analytics.
Atom is supported by default through jekyll-feed. With jekyll-feed, you can set configuration variables such as 'title', 'description', and 'author', in the _config.yml file.
Your atom feed file will be live at https://your.site/feed.xml example.
All social media icons are courtesy of Font Awesome. You can change which icons appear, as well as the account that they link to, in the _config.yml file.
Adam Blog 2.0 comes out of the box with MathJax, which allows you to display mathematical equations in your posts through the use of LaTeX. Just add Mathjax: yes in the frontmatter of your post.
<p style="text-align:center">
\(\theta_{t+1} = \theta_{t} - \dfrac{\eta}{\sqrt{\hat{v}_t} + \epsilon} \hat{m}_t\).
</p>
Adam Blog 2.0 provides syntax highlighting through fenced code blocks. Syntax highlighting allows you to display source code in different colors and fonts depending on what programming language is being displayed. You can find the full list of supported programming languages here. Another option is to embed your code through Gist.
You can choose the color theme for the syntax highlight in the _config.yml file:
highlight_theme: syntax-base16.monokai.dark # select a theme for the code highlighterSee the highlighter directory for reference on the options.
Jekyll offers support for GitHub Flavored Markdown, which allows you to format your posts using the Markdown syntax.
Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll's GitHub repo. If you have questions, you can ask them on Jekyll Talk.
If you would like to make a feature request, or report a bug or typo in the documentation, then please submit a GitHub issue. If you would like to make a contribution, then feel free to submit a pull request - as a bonus, I will credit all contributors below! If this is your first pull request, it may be helpful to read up on the GitHub Flow first.
Adam Blog 2.0 has been designed as a base for users to customize and fit to their own unique needs. Please keep this in mind when requesting features and/or submitting pull requests. Some examples of changes that I would love to see are things that would make the site easier to use, or better ways of doing things. Please avoid changes that do not benefit the majority of users.
This theme is completely free and open source software. You may use it however you want, as it is distributed under the MIT License. If you are having any problems, any questions or suggestions, feel free to file a GitHub issue.