diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c44f18..53ac52a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,19 +1,28 @@ ## Unreleased version -- Add YAML option `head-extra` which is similar to `footer-extra` but is used to include custom HTML code in a page's `` tag -- Add automatic navbar color detection (#702) -- Change navbar and footer background colour to be slightly darker, for better contrast with white page background -- Change the behaviour of `site-css` to include site-wide CSS file **before** page-specific files -- Rename internal css/js files from "main" to "beautifuljekyll" to make it easier for users to troubleshoot +- **BREAKING CHANGE** A lot of time was spent on rethinking the entire SEO and social media sharing model. It was redesigned to be more simple and customizable. The new documentation has a section dedicated to SEO and social media sharing of a page. Unfortunately some changes had to be made that are not backwards-compatible: + - Renamed `description` YAML option to `share-description` to be more clear + - Renamed `description` config parameter to `rss-description` since it was only used in RSS (the FAQ in the README explains the different between YAML options and config parameters if you're confused!) + - Removed YAML option `use-site-title` (you can now specify the exact title using `share-title`) + - Removed undocumented YAML options `meta-title` and `meta-description` +- Added `share-title` YAML option to give control over the search engine/social media title +- Added `head-extra` YAML option which is similar to `footer-extra` but is used to include custom HTML code in a page's `` tag +- Added automatic navbar color detection (#702) +- Added better SEO and social media sharing by adding a `share-title` YAML option and utilizing the `description` option +- Changed navbar and footer background colour to be slightly darker, for better contrast with white page background +- Changed the behaviour of `site-css` to include site-wide CSS file **before** page-specific files +- Renamed internal css/js files from "main" to "beautifuljekyll" to make it easier for users to troubleshoot + + ## v4.1.0 (2020-08-08) -- Add Open Graph `site_name` meta field to pages automatically -- Add `text-col `config setting for main text color (#694) -- Add `keywords` config setting to set the meta keywords on all pages (for SEO purposes) (#691) -- Add `mobile-theme-col` config setting to allow a mobile theme colour (#692) -- Add `site-css` config setting in the config file to provide CSS files that are used on all pages in the site (#695) -- Add YAML option `description`: creates the meta description on a page, intended to provide a brief description of the page for search engines and when the page is shared (#690) +- Added Open Graph `site_name` meta field to pages automatically +- Added `text-col `config setting for main text color (#694) +- Added `keywords` config setting to set the meta keywords on all pages (for SEO purposes) (#691) +- Added `mobile-theme-col` config setting to allow a mobile theme colour (#692) +- Added `site-css` config setting in the config file to provide CSS files that are used on all pages in the site (#695) +- Added YAML option `description`: creates the meta description on a page, intended to provide a brief description of the page for search engines and when the page is shared (#690) ## v4.0.1 (2020-07-13) @@ -27,11 +36,11 @@ - Image to share on social media will use the cover image or thumbnail if none is provided - All images (social media share, thumbnail, cover) can use either relative or absoluate paths. - Fixed issue where if a dropdown menu was the last item in the menu bar, it did not have a proper margin on the right -- Add social network links: Mastodon (#646), Google Scholar, ORCID (#670) -- Add support for sharing pages on new social network: VK (#657) +- Added social network links: Mastodon (#646), Google Scholar, ORCID (#670) +- Added support for sharing pages on new social network: VK (#657) - Use Open Graph type 'article' for blog posts (#669) - Use Twitter's large sumary card (large image) when there is a cover image, thumbnail image, or share image specified (#668) -- Make post images in the feed page smaller on smaller devices +- Made post images in the feed page smaller on smaller devices - Fixed jQuery version in staticman (#671) ## v3.0.0 (2020-05-07) @@ -41,26 +50,26 @@ - **BREAKING CHANGE** Removed `googlefonts` YAML parameter since googlefonts are just CSS so they can be loaded via `ext-css` - **BREAKING CHANGE** Upgraded from jQuery 1.11.2 to 3.4.2. This should not affect most people - Added `navbar-border-col` setting in the config file -- Add accessibility features where possible +- Added accessibility features where possible - Made the theme completely responsive by rewriting all CSS to use 'rem' instead of 'px' -- Rewrite and simplify some JavaScript code to use CSS or Bootstrap alternatives that weren't available in 2015 -- Remove most of the sample posts so that users only have two sample posts to learn from +- Rewrote and simplified some JavaScript code to use CSS or Bootstrap alternatives that weren't available in 2015 +- Removed most of the sample posts so that users only have two sample posts to learn from - Improvements to the README instructions ## v2.3.0 (2020-04-29) -- Add YAML option `footer-extra` for including custom content in the footer -- Fix issue: linking to a specific part of a page resulted in scrolling too far (#69) -- Add YAML option `nav-short` to have navbar permanently collapsed -- Add social network link: Calendly -- Fix bug where RSS link in footer was showing even when turned off +- Added YAML option `footer-extra` for including custom content in the footer +- Fixed issue: linking to a specific part of a page resulted in scrolling too far (#69) +- Added YAML option `nav-short` to have navbar permanently collapsed +- Added social network link: Calendly +- Fixed bug where RSS link in footer was showing even when turned off ## v2.2.0 (2020-04-27) -- Add social network link: Telegram (#625) (thanks @mashed-potatoes) +- Added social network link: Telegram (#625) (thanks @mashed-potatoes) - Moved the demo site to an independent URL: https://beautifuljekyll.com - Major documentation overhaul and cleanup of old files -- Fix a few bugs from the remote_theme migration +- Fixed a few bugs from the remote_theme migration ## v2.0.0 (2020-04-26) diff --git a/README.md b/README.md index d70f4b0..1138bb2 100644 --- a/README.md +++ b/README.md @@ -41,15 +41,14 @@ Check out [*What's New?*](https://beautifuljekyll.com/updates/) to see the lates - **Modern**: Uses the latest best practices and technologies to achieve nearly perfect scores on Google Chrome's Audit. - **Mobile-first**: Designed to look great on both large-screen and small-screen (mobile) devices. - **Highly customizable**: Many personalization settings such as changing the background colour/image, adding a logo. -- **Flexible usage**: Use Beautiful Jekyll directly on GitHub or using a Ruby gem - choose the best [development method](#build-your-website-in-3-steps) for you. -- **Battle-tested**: By using Beautiful Jekyll, you'll be joining tens of thousands of users who used this theme since 2015. -- **Links to your social media**: You can easily add links to any of your social media accounts in the footer of every page. +- **Flexible usage**: Use Beautiful Jekyll directly on GitHub or via a Ruby gem - choose the best [development method](#build-your-website-in-3-steps) for you. +- **Battle-tested**: By using Beautiful Jekyll, you'll be joining 50,000+ users enjoying this theme since 2015. +- **SEO and social media support**: Customize how your site looks on Google and when shared on social media. - **Comments support**: Add comments to any page using either [Disqus](https://disqus.com/), [Facebook comments](https://developers.facebook.com/docs/plugins/comments), [Utterances](https://utteranc.es/), or [Staticman](https://staticman.net). -- **Share blog posts on social media**: By default, all blog posts have buttons to allow people to share on Twitter/Facebook/LinkedIn. - **Tags**: Any blog post can be tagged with keywords, and an index page showing all the tags is automatically generated. -- **Tracking analytics**: Easily integrate Google Analytics, or other analytics platforms, to track visits to your website. +- **Analytics**: Easily integrate Google Analytics, or other analytics platforms, to track visits to your website. - **Photos support**: Any page can have a cover photo around its title, and any blog post can have an associated image. -- **More advanced features**: I wrote [a blog post](https://deanattali.com/2015/03/12/beautiful-jekyll-how-to-build-a-site-in-minutes/) describing some more advanced features that I used in my website that can be used in any beautiful-jekyll site. +- **RSS**: An RSS feed is automatically created, so you can even host a podcast easily with Beautiful Jekyll. # Build your website in 3 steps @@ -117,7 +116,7 @@ subtitle: Here you'll find all the ways to get in touch with me --- ``` -If you don't want to use any parameters on a page, you still need to use the two dashed lines. If you don't, then your file will be shown as-is withou the Beautiful Jekyll template. +If you don't want to use any parameters on a page, you still need to use the two dashed lines. If you don't, then your file will be shown as-is without the Beautiful Jekyll template. You can look at the top of [`aboutme.md`](https://raw.githubusercontent.com/daattali/beautiful-jekyll/master/aboutme.md) as an example. @@ -125,7 +124,7 @@ You can look at the top of [`aboutme.md`](https://raw.githubusercontent.com/daat # Supported parameters -Below is a list of the parameters that **Beautiful Jekyll** supports (any of these can be added to the YAML front matter of any page). Remember to also look in the `_config.yml` file to see additional site-wide settings. +Below is a list of the parameters that Beautiful Jekyll supports (any of these can be added to the YAML front matter of any page). Remember to also look in the `_config.yml` file to see additional site-wide settings. ## Main parameters @@ -137,8 +136,19 @@ title | Page or blog post title subtitle | Short description of page or blog post that goes under the title tags | List of tags to categorize the post. Separate the tags with commas and place them inside square brackets. Example: `[personal, analysis, finance]` cover-img | Include a large full-width image at the top of the page. You can either provide the path to a single image (eg. `"/path/to/img"`) , or a list of images to cycle through (eg. `["/path/img1", "/path/img2"]`). If you want to add a caption to an image, then the image should be provided as `{"/path/to/img" : "Caption of image"}`. +thumbnail-img | For blog posts, if you want to add a thumbnail that will show up in the feed, use `thumbnail-img: /path/to/image`. If no thumbnail is provided, then `cover-img` will be used as the thumbnail. You can use `thumbnail-img: ""` to disable a thumbnail. comments | If you want do add comments to a specific page, use `comments: true`. Comments only work if you enable one of the comments providers (Facebook, disqus, staticman, utterances) in `_config.yml` file. Comments are automatically enabled on blog posts but not on other pages; to turn comments off for a specific post, use `comments: false`. +## Parameters for SEO and social media sharing + +These parameters let you control what information shows up when a page is shown in a search engine (such as Google) or gets shared on social media (such as Twitter/Facebook). + +Parameter | Description +----------- | ----------- +share-title | A title for the page. If not provided, then `title` will be used, and if that's missing then the site title (from `_config.yml`) is used. +share-description | A brief description of the page. If not provided, then `subtitle` will be used, and if that's missing then an excerpt from the page content is used. +share-img | The image to show. If not provided, then `cover-img` or `thumbnail-img` will be used if one of them is provided. + ## Less commonly used parameters These are parameters that you may not use often, but can come in handy sometimes. @@ -147,9 +157,6 @@ Parameter | Description ----------- | ----------- readtime | If you want a post to show how many minutes it will take to read it, use `readtime: true`. show-avatar | If you have an avatar configured in the `_config.yml` but you want to turn it off on a specific page, use `show-avatar: false`. -thumbnail-img | For blog posts, if you want to add a thumbnail that'll show up next to the post's excerpt in the feed, use `thumbnail-img: /path/to/image`. If no thumbnail is provided, then `cover-img` will be used as the thumbnail. You can use `thumbnail-img: ""` to disable a thumbnail. -share-img | The image to use when sharing the page to social media. If not provided, then `cover-img` or `thumbnail-img` will be used. -description | A brief description of the page (used in search engines and when the page is shared). If not provided, the page subtitle will be used. social-share | By default, every blog post has buttons to share the page on social media. If you want to turn this feature off, use `social-share: false`. nav-short | By default, the navigation bar gets shorter after scrolling down the page. If you want the navigation bar to always be short on a certain page, use `nav-short: true` gh-repo   | If you want to show GitHub buttons at the top of a post, this sets the GitHub repo name (eg. `daattali/beautiful-jekyll`). You must also use the `gh-badge` parameter to specify what buttons to show. @@ -165,7 +172,6 @@ Parameter | Description footer-extra | If you want to include extra information in the footer (below the social media icons), create an HTML file in the `_includes/` folder (for example `_includes/myinfo.html`) and set `footer-extra` to the name of the file (for example `footer-extra: myinfo.html`) head-extra | Works in a similar way to `footer-extra`, but used if you have any HTML code that needs to be included in the `` tag of the page. language | HTML language code to be set on the page's <html> element. -use-site-title | If you want to use the site title rather than the page title as the HTML document title, use `use-site-title: true`. js | List of local JavaScript files to include in the page (eg. `/assets/js/mypage.js`) ext-js | List of external JavaScript files to include in the page (eg. `//cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.2/underscore-min.js`). External JavaScript files that support [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) can be specified using the `href` and `sri` parameters eg.
`href: "//code.jquery.com/jquery-3.1.1.min.js"`
`sri: "sha256-hVVnYaiADRTO2PzUGmuLJr8BLUSjGIZsDYGmIJLv2b8="` css | List of local CSS files to include in the page diff --git a/_config.yml b/_config.yml index 216d484..b079b58 100644 --- a/_config.yml +++ b/_config.yml @@ -1,11 +1,8 @@ -# --- Basic options --- # +# --- Required options --- # # Name of website title: My website -# Short description of your site -description: A virtual proof that I'm awesome - # Your name to show in the footer author: Some Person @@ -32,17 +29,15 @@ round-avatar: true #title-img: /path/to/image -# --- Footer options --- # +# --- Footer social media links --- # # Select the social network links that you want to show in the footer. # Uncomment the links you want to show and add your information to each one. -# If you don't want to show a link to an RSS feed, set rss to "false". social-network-links: email: "someone@example.com" facebook: deanattali github: daattali twitter: daattali - rss: true # reddit: yourname # linkedin: daattali # xing: yourname @@ -61,6 +56,10 @@ social-network-links: # ORCID: your ORCID ID # google-scholar: your google scholar +# If you want to show a link to an RSS in the footer, add the site description here. +# If you don't want to show an RSS link, remove the following line. +rss-description: This website is a virtual proof that I'm awesome + # --- General options --- # # Select which social network share links to show in posts @@ -77,7 +76,7 @@ url-pretty: "MyWebsite.com" # Create a "tags" index page and make tags on each post clickable link-tags: true -# Excerpt Word Length - Truncates the excerpt of posts on the index page to the specified number of words +# Excerpt word length - Truncate the excerpt of each post on the feed page to the specified number of words excerpt_length: 50 # The keywords to associate with your website, for SEO purposes @@ -165,10 +164,6 @@ footer-link-col: "#404040" # --- Misc --- # -# Character used to separate site title and description in HTML document title -# and RSS feed title -title-separator: "-" - # Ruby Date Format to show dates of posts date_format: "%B %-d, %Y" diff --git a/_includes/head.html b/_includes/head.html index 1f3fbe3..fc38997 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -2,21 +2,33 @@ - {% if page.use-site-title %}{{ site.title }} {{ site.title-separator | default: '-' }} {{ site.description }}{% elsif page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %} + {%- capture title -%} + {%- if page.share-title -%} + {{ page.share-title }} + {%- elsif page.title -%} + {{ page.title }} + {%- else -%} + {{ site.title }} + {%- endif -%} + {%- endcapture -%} + + {%- capture description -%} + {%- if page.share-description -%} + {{ page.share-description }} + {%- elsif page.subtitle -%} + {{ page.subtitle }} + {%- else -%} + {% assign excerpt_length = site.excerpt_length | default: 50 %} + {{ page.content | strip_html | xml_escape | truncatewords: excerpt_length }} + {%- endif -%} + {%- endcapture -%} + + {{ title }} {% if site.author %} {% endif %} - {%- capture description -%} - {%- if page.description -%} - {{ page.description }} - {%- elsif page.subtitle -%} - {{ page.subtitle }} - {%- else -%} - {{ site.description }} - {%- endif -%} - {%- endcapture -%} {% if site.mobile-theme-col %} @@ -27,7 +39,7 @@ {% endif %} - + {% include gtag.html %} {% include gtm_head.html %} @@ -71,27 +83,7 @@ {% endif %} - {%- capture share-title -%} - {%- if page.meta-title -%} - {{ page.meta-title }} - {%- elsif page.title -%} - {{ page.title }} - {%- else -%} - {{ site.title }} - {%- endif -%} - {%- endcapture -%} - - {%- capture share-description -%} - {%- if page.meta-description -%} - {{ page.meta-description }} - {%- elsif page.subtitle -%} - {{ page.subtitle }} - {%- else -%} - {{ page.content | strip_html | xml_escape | truncatewords: 50 }} - {%- endif -%} - {%- endcapture -%} - - {%- capture share-img -%} + {%- capture img -%} {%- if page.share-img -%} {{ page.share-img }} {%- elsif page.cover-img -%} @@ -106,33 +98,28 @@ {{ site.avatar }} {% endif %} {%- endcapture -%} - {%- assign share-img=share-img | strip -%} + {%- assign img=img | strip -%} - - + + - {% if share-img != "" %} - + {% if img != "" %} + {% endif %} {% if page.id %} - {% else %} - - {% endif %} - - {% if page.id %} {% else %} + {% endif %} - - {% if share-img != "" and share-img != site.avatar %} + {% if img != "" and img != site.avatar %} {% else %} @@ -140,11 +127,11 @@ - - + + - {% if share-img != "" %} - + {% if img != "" %} + {% endif %} {% if site.matomo %} diff --git a/_includes/social-networks-links.html b/_includes/social-networks-links.html index af2754c..96379c0 100644 --- a/_includes/social-networks-links.html +++ b/_includes/social-networks-links.html @@ -1,6 +1,6 @@