Hunter Krajcik

Hunter Krajcik

1672467540

Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts

Jekyll Feed plugin

A Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts

Installation

Add this line to your site's Gemfile:

gem 'jekyll-feed'

And then add this line to your site's _config.yml:

plugins:
  - jekyll-feed

:warning: If you are using Jekyll < 3.5.0 use the gems key instead of plugins.

Usage

The plugin will automatically generate an Atom feed at /feed.xml.

Optional configuration options

The plugin will automatically use any of the following configuration variables, if they are present in your site's _config.yml file.

  • title or name - The title of the site, e.g., "My awesome site"
  • description - A longer description of what your site is about, e.g., "Where I blog about Jekyll and other awesome things"
  • url - The URL to your site, e.g., https://example.com. If none is provided, the plugin will try to use site.github.url.
  • author - Global author information (see below)

Already have a feed path?

Do you already have an existing feed someplace other than /feed.xml, but are on a host like GitHub Pages that doesn't support machine-friendly redirects? If you simply swap out jekyll-feed for your existing template, your existing subscribers won't continue to get updates. Instead, you can specify a non-default path via your site's config.

feed:
  path: /blog/feed.atom

To note, you shouldn't have to do this unless you already have a feed you're using, and you can't or wish not to redirect existing subscribers.

Optional front matter

The plugin will use the following post metadata, automatically generated by Jekyll, which you can override via a post's YAML front matter:

  • date
  • title
  • excerpt
  • id
  • category
  • tags

Additionally, the plugin will use the following values, if present in a post's YAML front matter:

image - URL of an image that is representative of the post (can also be passed as image.path)

author - The author of the post, e.g., "Dr. Jekyll". If none is given, feed readers will look to the feed author as defined in _config.yml. Like the feed author, this can also be an object or a reference to an author in _data/authors.yml (see below).

description - A short description of the post.

Author information

TL;DR: In most cases, put author: [your name] in the document's front matter, for sites with multiple authors. If you need something more complicated, read on.

There are several ways to convey author-specific information. Author information is found in the following order of priority:

  1. An author object, in the documents's front matter, e.g.:
author:
  twitter: benbalter
  1. An author object, in the site's _config.yml, e.g.:
author:
  twitter: benbalter
  1. site.data.authors[author], if an author is specified in the document's front matter, and a corresponding key exists in site.data.authors. E.g., you have the following in the document's front matter:
author: benbalter

And you have the following in _data/authors.yml:

benbalter:
  picture: /img/benbalter.png
  twitter: jekyllrb

potus:
  picture: /img/potus.png
  twitter: whitehouse

In the above example, the author benbalter's Twitter handle will be resolved to @jekyllrb. This allows you to centralize author information in a single _data/authors file for site with many authors that require more than just the author's username.

Pro-tip: If authors is present in the document's front matter as an array (and author is not), the plugin will use the first author listed.

  1. An author in the document's front matter (the simplest way), e.g.:
author: benbalter
  1. An author in the site's _config.yml, e.g.:
author: benbalter

Meta tags

The plugin exposes a helper tag to expose the appropriate meta tags to support automated discovery of your feed. Simply place {% feed_meta %} someplace in your template's <head> section, to output the necessary metadata.

SmartyPants

The plugin uses Jekyll's smartify filter for processing the site title and post titles. This will translate plain ASCII punctuation into "smart" typographic punctuation. This will not render or strip any Markdown you may be using in a title.

Jekyll's smartify filter uses kramdown as a processor. Accordingly, if you do not want "smart" typographic punctuation, disabling them in kramdown in your _config.yml will disable them in your feed. For example:

kramdown:
  smart_quotes:               apos,apos,quot,quot
  typographic_symbols:        {hellip: ...}

Custom styling

Want to style what your feed looks like in the browser? When a XSLT Styleheet file named feed.xslt.xml exists at the root of your repository, a link to this stylesheet is added to the generated feed.

Why Atom, and not RSS?

Great question. In short, Atom is a better format. Think of it like RSS 3.0. For more information, see this discussion on why we chose Atom over RSS 2.0.

Categories

Jekyll Feed can generate feeds for each category. Simply define which categories you'd like feeds for in your config:

feed:
  categories:
    - news
    - updates

Posts limit

By default the plugin limits the number of posts in the feed to 10. Simply define a new limit in your config:

feed:
  posts_limit: 20

Collections

Jekyll Feed can generate feeds for collections other than the Posts collection. This works best for chronological collections (e.g., collections with dates in the filenames). Simply define which collections you'd like feeds for in your config:

feed:
  collections:
    - changes

By default, collection feeds will be outputted to /feed/<COLLECTION>.xml. If you'd like to customize the output path, specify a collection's custom path as follows:

feed:
  collections:
    changes:
      path: "/changes.atom"

Finally, collections can also have category feeds which are outputted as /feed/<COLLECTION>/<CATEGORY>.xml. Specify categories like so:

feed:
  collections:
    changes:
      path: "/changes.atom"
      categories:
        - news
        - updates

Excerpt Only flag

Optional flag excerpt_only allows you to exclude post content from the Atom feed. Default value is false for backward compatibility.

When in config.yml is true than all posts in feed will be without <content> tags.

feed:
  excerpt_only: true

The same flag can be used directly in post file. It will be disable <content> tag for selected post. Settings in post file has higher priority than in config file.

Tags

To automatically generate feeds for each tag you apply to your posts you can add a tags setting to your config:

feed:
  tags: true

If there are tags you don't want included in this auto generation you can exclude them

feed:
  tags:
    except:
      - tag-to-exclude
      - another-tag

If you wish to change the location of these auto generated feeds (/feed/by_tag/<TAG>.xml by default) you can provide an alternative folder for them to live in.

feed:
  tags:
    path: "alternative/path/for/tags/feeds/"

If you only want to generate feeds for a few tags you can also set this.

feed:
  tags:
    only:
      - tag-to-include
      - another-tag

Note that if you include a tag that is excluded a feed will not be generated for it.

Skip development

Use disable_in_development: true if you want to turn off feed generation when jekyll.environment == "development", but don't want to remove the plugin (so you don't accidentally commit the removal). Default value is false.

feed:
  disable_in_development: true

Contributing

  1. Fork it (https://github.com/jekyll/jekyll-feed/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Download Details:

Author: jekyll
Source Code: https://github.com/jekyll/jekyll-feed 
License: MIT license

#atom #ruby #jekyll #plugin 

Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts
Gordon Matlala

Gordon Matlala

1667452860

Architect: A Jekyll Theme for GitHub Pages

The Architect theme

Architect is a Jekyll theme for GitHub Pages. You can preview the theme to see what it looks like, or even use it today.

Usage

To use the Architect theme:

Add the following to your site's _config.yml:

remote_theme: pages-themes/architect@v0.2.0
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one

Optionally, if you'd like to preview your site on your computer, add the following to your site's Gemfile:

gem "github-pages", group: :jekyll_plugins

Customizing

Configuration variables

Architect will respect the following variables, if set in your site's _config.yml:

title: [The title of your site]
description: [A short description of your site's purpose]

Additionally, you may choose to set the following optional variables:

show_downloads: ["true" or "false" (unquoted) to indicate whether to provide a download URL]
google_analytics: [Your Google Analytics tracking ID]

Stylesheet

If you'd like to add your own custom styles:

Create a file called /assets/css/style.scss in your site

Add the following content to the top of the file, exactly as shown:

---
---

@import "{{ site.theme }}";

Add any custom CSS (or Sass, including imports) you'd like immediately after the @import line

Note: If you'd like to change the theme's Sass variables, you must set new values before the @import line in your stylesheet.

Layouts

If you'd like to change the theme's HTML layout:

  1. For some changes such as a custom favicon, you can add custom files in your local _includes folder. The files provided with the theme provide a starting point and are included by the original layout template.
  2. For more extensive changes, copy the original template from the theme's repository
    (Pro-tip: click "raw" to make copying easier)
  3. Create a file called /_layouts/default.html in your site
  4. Paste the default layout content copied in the first step
  5. Customize the layout as you'd like

Customizing Google Analytics code

Google has released several iterations to their Google Analytics code over the years since this theme was first created. If you would like to take advantage of the latest code, paste it into _includes/head-custom-google-analytics.html in your Jekyll site.

Overriding GitHub-generated URLs

Templates often rely on URLs supplied by GitHub such as links to your repository or links to download your project. If you'd like to override one or more default URLs:

Look at the template source to determine the name of the variable. It will be in the form of {{ site.github.zip_url }}.

Specify the URL that you'd like the template to use in your site's _config.yml. For example, if the variable was site.github.url, you'd add the following:

github:
  zip_url: http://example.com/download.zip
  another_url: another value

When your site is built, Jekyll will use the URL you specified, rather than the default one provided by GitHub.

Note: You must remove the site. prefix, and each variable name (after the github.) should be indent with two space below github:.

For more information, see the Jekyll variables documentation.

Roadmap

See the open issues for a list of proposed features (and known issues).

Project philosophy

The Architect theme is intended to make it quick and easy for GitHub Pages users to create their first (or 100th) website. The theme should meet the vast majority of users' needs out of the box, erring on the side of simplicity rather than flexibility, and provide users the opportunity to opt-in to additional complexity if they have specific needs or wish to further customize their experience (such as adding custom CSS or modifying the default layout). It should also look great, but that goes without saying.

Contributing

Interested in contributing to Architect? We'd love your help. Architect is an open source project, built one contribution at a time by users like you. See the CONTRIBUTING file for instructions on how to contribute.

Previewing the theme locally

If you'd like to preview the theme locally (for example, in the process of proposing a change):

  1. Clone down the theme's repository (git clone https://github.com/pages-themes/architect)
  2. cd into the theme's directory
  3. Run script/bootstrap to install the necessary dependencies
  4. Run bundle exec jekyll serve to start the preview server
  5. Visit localhost:4000 in your browser to preview the theme

Running tests

The theme contains a minimal test suite, to ensure a site with the theme would build successfully. To run the tests, simply run script/cibuild. You'll need to run script/bootstrap once before the test script will work.

Download Details:

Author: Pages-themes
Source Code: https://github.com/pages-themes/architect 
License: CC0-1.0 license

#jekyll #theme #githubpages 

Architect: A Jekyll Theme for GitHub Pages
Gordon Matlala

Gordon Matlala

1667449020

Hacker-Blog: A Minimalistic, Responsive Jekyll Theme Built for Hackers

The Hacker-Blog theme

Hacker-Blog is a minimalistic, responsive jekyll theme built for hackers. It is based on the hacker theme for project pages.

Included

  1. Pagination
  2. SEO tags
  3. Archive Page
  4. About Page
  5. RSS (https://base-url/atom)
  6. Sitemap (https://base-url/sitemap)
  7. Google Analytics (optional)

Usage

  1. Fork and Clone this repository
  2. Customize your blog
  3. Add a new post in _posts/ directory with proper name format (as shown in placeholder posts)
  4. Commit and push to master on a repository named <githubusername.github.io>.
  5. Visit <githubusername>.github.io

Local Build

If you want to see the changes before pushing the blog to Github, do a local build.

  1. gem install jekyll
  2. gem install jekyll-seo-tag
  3. gem install jekyll-paginate
  4. gem install jekyll-sitemap
  5. (cd to the blog directory, then:) jekyll serve --watch --port 8000
  6. Go to http://0.0.0.0:8000/ in your web browser.

Note: In case you have set a baseurl different than / in _config.yml, go to http://0.0.0.0:8000/BASEURL/ instead.

Local build using docker

docker run --rm -p 8000:8000 \
  --volume="LOCATION_OF_YOUR_JEKYLL_BLOG:/srv/jekyll" \
  -it tocttou/jekyll:3.5 \
  jekyll serve --watch --port 8000

Replace LOCATION_OF_YOUR_JEKYLL_BLOG with the full path of your blog repository. Visit http://localhost:8000/ to access the blog.

Note: In case you have set a baseurl different than / in _config.yml, go to http://0.0.0.0:8000/BASEURL/ instead.

Customizing

Configuration variables

Edit the _config.yml file and set the following variables:

title: [The title of your blog]
description: [A short description of your blog's purpose]
author:
  name: [Your name]
  email: [Your email address]
  url: [URL of your website]

baseurl: [The base url for this blog.]

paginate: [Number of posts in one paginated section (default: 3)]
owner: [Your name]
year: [Current Year]

Note: All links in the site are prepended with baseurl. Default baseurl is /. Any other baseurl can be setup like baseurl: /hacker-blog, which makes the site available at http://domain.name/hacker-blog.

Additionally, you may choose to set the following optional variables:

google_analytics: [Your Google Analytics tracking ID]

About Page

Edit about.md

Layout

If you would like to modify the site style:

HTML

Footer: Edit _includes/footer.html

Header: Edit _includes/header.html

Links in the header: Edit _includes/links.html

Meta tags, blog title display, and additional CSS: Edit _includes/head.html

Index page layout: Edit _layouts/default.html

Post layout: Edit _layouts/post.html

CSS

Site wide CSS: Edit _sass/base.scss

Custom CSS: Make _sass/custom.scss and use it. Then add @import "custom"; to css/main.scss

404 page

Edit 404.md

Demo: https://ashishchaudhary.in/hacker-blog

Download Details:

Author: Tocttou
Source Code: https://github.com/tocttou/hacker-blog 
License: CC0-1.0 license

#jekyll #blog #theme 

Hacker-Blog: A Minimalistic, Responsive Jekyll Theme Built for Hackers
Gordon Matlala

Gordon Matlala

1667445120

Import Academic Publications From Bibtex to Your Markdown Website

Hugo Academic CLI

📚 Import publications from your reference manager to Hugo

Features

  • Import publications, including books, conference proceedings and journals, from your reference manager to your static site generator
    • Simply export a BibTeX file from your reference manager, such as Zotero, and provide this as the input
  • Hugo command pass-through

Community

❤️ Support this open-source software

To help us develop this Academic CLI tool and the associated Wowchemy software sustainably under the MIT license, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship and contributing.

Support development of the Academic CLI:

Prerequisites

  1. Create a Hugo website such as by using the Hugo Academic Starter template for the Wowchemy website builder
  2. Download your site from GitHub, installing Hugo and its dependencies
  3. Install Python 3.6+ if it’s not already installed
  4. Version control your website
    • Ideally, version control your site with Git so that you can review the proposed changes and accept or reject them without risking breaking your site
    • Otherwise, if not using Git, backup your site folder prior to running this tool

Installation

Open your Terminal or Command Prompt app and install the Academic CLI tool:

pip3 install -U academic

Alternatively, install Academic CLI v0.5.1 if you do not wish to install Hugo on your computer:

pip3 install academic==0.5.1

Or, help test the lastest development version:

pip3 install -U git+https://github.com/wowchemy/hugo-academic-cli.git

Usage

Use the cd command to navigate to your website folder in the terminal:

cd <MY_WEBSITE_FOLDER>

Help:

academic

Import publications:

Say we downloaded our publications from our reference manager, such as Zotero, to a file named my_publications.bib within the website folder. We can import them into the default content/publication/ folder with:

academic import --bibtex my_publications.bib

Import publications to a specific folder (e.g. content/zh/publication):

Say our site has multiple languages, we may want to output the publications to a specific folder with:

academic import --bibtex my_publications.bib --publication-dir content/zh/publication/

Optional arguments:

  • --publication-dir PUBLICATION_DIR Folder to import publications to (defaults to content/publication)
  • --overwrite Overwrite any existing publications in the output folder
  • --normalize Normalize tags by converting them to lowercase and capitalizing the first letter (e.g. "sciEnCE" -> "Science")
  • --featured Flag these publications as featured (to appear in Featured Publications widget)
  • --verbose or -v Show verbose messages
  • --help Help

After importing publications, a full text PDF and image can be associated with each item and further details added via extra parameters.

Run a Hugo command (pass-through):

academic server

Contribute

Interested in contributing to open source and open science?

Learn how to contribute code on Github.

Check out the open issues and contribute a Pull Request.

For local development, clone this repository and use Pipenv to install the tool using the following commands:

git clone https://github.com/wowchemy/hugo-academic-cli.git
cd hugo-academic-cli
pip3 install pipenv
pipenv install -e .

Preparing a contribution:

  • Lint: make lint
  • Format: make format
  • Test: make test

Download Details:

Author: Wowchemy
Source Code: https://github.com/wowchemy/hugo-academic-cli 
License: MIT license

#jekyll #cli #admin 

Import Academic Publications From Bibtex to Your Markdown Website
Gordon Matlala

Gordon Matlala

1667441220

Jekyll-gist: Liquid Tag for Displaying GitHub Gists in Jekyll Sites

Jekyll::Gist

Liquid tag for displaying GitHub Gists in Jekyll sites: {% gist %}.

Installation

Add this line to your application's Gemfile:

$ gem 'jekyll-gist'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-gist

Then add the following to your site's _config.yml:

plugins:
  - jekyll-gist

💡 If you are using a Jekyll version less than 3.5.0, use the gems key instead of plugins.

Usage

Use the tag as follows in your Jekyll pages, posts and collections:

{% gist c08ee0f2726fd0e3909d %}

This will create the associated script tag:

<script src="https://gist.github.com/parkr/c08ee0f2726fd0e3909d.js"> </script>

You may optionally specify a filename after the gist_id:

{% gist c08ee0f2726fd0e3909d test.md %}

This will produce the correct URL to show just the specified file in your post rather than the entire Gist.

Pro-tip: If you provide a personal access token with Gist scope, as the environmental variable JEKYLL_GITHUB_TOKEN, Jekyll Gist will use the Gist API to speed up site generation.

Disabling noscript support

By default, Jekyll Gist will make an HTTP call per Gist to retrieve the raw content of the Gist. This information is used to propagate noscript tags for search engines and browsers without JavaScript support. If you'd like to disable this feature, for example, to speed up builds locally, add the following to your site's _config.yml:

gist:
  noscript: false

Contributing

  1. Fork it ( https://github.com/jekyll/jekyll-gist/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Download Details:

Author: jekyll
Source Code: https://github.com/jekyll/jekyll-gist 
License: MIT license

#jekyll #github #ruby 

Jekyll-gist: Liquid Tag for Displaying GitHub Gists in Jekyll Sites
Gordon Matlala

Gordon Matlala

1667437440

Vanilla-back-to-top: Simple and Smooth Back to Top Button

Vanilla Back To Top

Simple and tiny Back To Top button with no dependencies. Hides when on top, scrolls up smoothly when clicked. Works equally great with Vue, React, Angular and without frameworks on Jekyll, Hugo and Hexo


 

Live demo

Features

How to use

Add this to <body> of your HTML:

<script src="https://unpkg.com/vanilla-back-to-top@7.2.1/dist/vanilla-back-to-top.min.js"></script>
<script>addBackToTop({
  diameter: 56,
  backgroundColor: 'rgb(255, 82, 82)',
  textColor: '#fff'
})</script>

For alternative installation see INSTALL

See EXAMPLES

For all options see OPTIONS

Support me with a star ♥

Download Details:

Author: vfeskov
Source Code: https://github.com/vfeskov/vanilla-back-to-top 
License: MIT license

#jekyll #react #generator #angular #vue 

Vanilla-back-to-top: Simple and Smooth Back to Top Button
Gordon Matlala

Gordon Matlala

1667433540

Tutorials: Codebar's Tutorials

Getting started

This is a GitHub Pages repo, so you can render the pages with Jekyll. First make sure to install the version of Ruby indicated in .ruby-version, as well as the bundler gem. Then:

  1. bundle install, which will install Jekyll
  2. bundle exec jekyll serve --watch
  3. go to http://localhost:4000

(you could also use your favourite manager, chruby, rbenv, rvm, etc. See instructions for rvm at the end of this README)

If you are just updating or adding new tutorials, follow steps 1 to 3 only.

If you also want to make changes to the structure of the site (i.e. if you want to modify the site's Javascript files) and run the tests, you need to install Node (follow the link for installation instructions). Then:

$ npm install
$ gulp

and go to http://localhost:4000/test/specrunner.html to run the tests. Tests should be green.

Gulp is only used for development, not in production. In your local copy of this repo, it will concatenate and minify the files inside the javascripts-dev folder, as well as watch for changes in that folder. The concatenated and minified JS file will be generated inside the javascripts folder. You can push both folders when you are finished with your changes. GitHub pages will then generate the site in production with whatever is inside the javascripts folder.

Getting in Touch

You can go to the general codebar Slack channel here or the dedicated tutorials channel here. Use it to get in touch and chat to other codebar students/coaches, or if you need help.

If you are not on Slack use this link to get an invite.

Contributing

We encourage you to contribute with your suggestions and corrections. Head to our issues page and open a new issue or help on the existing ones.

General tutorial rule

All tutorials get the students to build something that they are able to show around at the end of the workshop.

All tutorials follow a structure:

  • Objectives - "In this tutorial we are going to look at..."
  • Goals - "By the end of this tutorial you will have..."
  • Then the exercises.
    • Bonus - This is not always required but if you feel there is something that could be added then please include it.
    • Further reading - Again this is not always required but if you feel there was something in the tutorials that could be covered in more depth then please include any good reading materials/videos or extra tutorials.

Repetition is good. A tutorial can contain multiple exercises that ask the students to take similar steps (e.g. for HTTP Requests one exercise introduces GET, another has GET and POST etc).

Explaining and getting the students to focus on one new thing at a time, presenting students with lots of new content and usage examples can be confusing.

Before starting to write a new tutorial please speak with someone from codebar to see whether it is of interest to students.

To add downloadable files to a new or existing tutorial:

  • Add a folder with your exercise files inside the tutorial folder. For example, for Javascript lesson 3:
js/lesson3/
├── assets/
├── files/
│   ├── index.html
│   ├── jquery.js
│   ├── script.js
│   └── style.css
└── tutorial.md
  • Add a frontmatter variable files to the tutorial page with a list of the files you added, including folder name:
---
layout: page
title: Introduction to jQuery
files:
  - files/index.html
  - files/jquery.js
  - files/script.js
  - files/style.css
---
  • In the copy of the tutorial, add your link to the files, making it point to just download:
Download the files that you will need to work through the example
[here](download).

And you're done. Commit and push as usual.

RVM

Another way of installing the project dependencies is via RVM. Follow the quick installation guide and then run:

$ rvm install 2.2.1  # inside `codebar/tutorials` folder
$ rvm gemset use codebar-tutorial --create
$ gem install bundler
$ bundle install
$ jekyll serve  # go to http://127.0.0.1:4000

If you also want to make changes to the JavaScript of the site, you'll need to have Node installed. This can be done with a tool like NVM.

This is the source code for http://tutorials.codebar.io

Download Details:

Author: codebar
Source Code: https://github.com/codebar/tutorials 
License: CC BY-NC-SA 4.0

#jekyll #javascript #ruby #css #python 

Tutorials: Codebar's Tutorials
Gordon Matlala

Gordon Matlala

1667429580

Resume: A Minimalist Resume Template for Jekyll and Hexo

Resume

A Minimalist Resume Template for Jekyll and Hexo

Introduction

This is a responsive minimal résumé template made by Crisp, powered by Jekyll. And we also provide an official Hexo port for Hexo users.

You may config all the data in yaml and make it your own résumé. Then, you might use on GitHub Pages, your website, or wherever you want.

English 简体中文

DEMO

Features

  • Simple, elegant, and minimal design
  • PC and mobile friendly, but it looks better on PC
  • PDF supports and print friendly
  • Flexible and extensible

Usage

Local Mode

Clone the repo

git clone https://github.com/crispgm/resume.git

Install Jekyll

gem install jekyll

Config your résumé data

The baseurl is required in _config.yml if you serve this page as part of your website. And your contact information, EDUCATION, SKILLS, EXPERIENCE, and PROJECTS data will be set in _data/resume.yml.

Run and Debug

jekyll serve

Build

jekyll build

Gem-based Theme

Create a Gemfile

source "https://rubygems.org"

gem "jekyll-theme-minimal-resume"

And then,

bundle install

Init _config.yml

title: Résumé Title
baseurl: "/resume/"
theme: "jekyll-theme-minimal-resume"

Create a index.html

---
layout: resume
---

Create _data/resume.yml and fill in your resume data. Example data is available here.

Data Format

Contact

contact:
  - icon: fa-envelope
    text: youremail@example.com
  - icon: fa-phone-square
    text: your-phone-num
  - icon: fa-globe
    text: your-website.com
    link: https://crispgm.github.io/resume/resume.html

FontAwesome iconfont is embedded, so use the fa- class name as icon. link is optional, present if you want a link for your web version.

Colors

There are a set of colorscheme. color may be specified in _config.yml. The default colorscheme is gray.

color: gray

Colors powered by Open-Color:

  • red
  • pink
  • grape
  • violet
  • indigo
  • blue
  • cyan
  • teal
  • green
  • lime
  • yellow
  • orange

Colors powered by Nord:

  • nord

Extending Sections

Add new section in _data/resume.yml

languages:
  - name: English
    proficiency: Professional working proficiency
  - name: Mandarin Chinese
    proficiency: Native or bilingual proficiency

Add section to _layouts/resume.html:

<section id="languages">
  <div class="section-title">Language</div>
  <div class="section-content">
    {% for lang in site.data.resume.languages %}
    <div class="block">
      <div class="block-title">{{ lang.name }}</div>
      <div class="block-content">{{ lang.proficiency }}</div>
    </div>
    {% endfor %}
  </div>
</section>

Showcases

Feel free to add yours here.

Download Details:

Author: Crispgm
Source Code: https://github.com/crispgm/resume 
License: MIT license

#jekyll #resume #template #theme 

Resume: A Minimalist Resume Template for Jekyll and Hexo
Gordon Matlala

Gordon Matlala

1667425500

Slate: A Jekyll Theme for GitHub Pages

The Slate theme 

Slate is a Jekyll theme for GitHub Pages. You can preview the theme to see what it looks like, or even use it today.

Usage

To use the Slate theme:

Add the following to your site's _config.yml:

remote_theme: pages-themes/slate@v0.2.0
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one

Optionally, if you'd like to preview your site on your computer, add the following to your site's Gemfile:

gem "github-pages", group: :jekyll_plugins

Customizing

Configuration variables

Slate will respect the following variables, if set in your site's _config.yml:

title: [The title of your site]
description: [A short description of your site's purpose]

Additionally, you may choose to set the following optional variables:

show_downloads: ["true" or "false" (unquoted) to indicate whether to provide a download URL]
google_analytics: [Your Google Analytics tracking ID]

Stylesheet

If you'd like to add your own custom styles:

Create a file called /assets/css/style.scss in your site

Add the following content to the top of the file, exactly as shown:

---
---

@import "{{ site.theme }}";

Add any custom CSS (or Sass, including imports) you'd like immediately after the @import line

Note: If you'd like to change the theme's Sass variables, you must set new values before the @import line in your stylesheet.

Layouts

If you'd like to change the theme's HTML layout:

  1. For some changes such as a custom favicon, you can add custom files in your local _includes folder. The files provided with the theme provide a starting point and are included by the original layout template.
  2. For more extensive changes, copy the original template from the theme's repository
    (Pro-tip: click "raw" to make copying easier)
  3. Create a file called /_layouts/default.html in your site
  4. Paste the default layout content copied in the first step
  5. Customize the layout as you'd like

Customizing Google Analytics code

Google has released several iterations to their Google Analytics code over the years since this theme was first created. If you would like to take advantage of the latest code, paste it into _includes/head-custom-google-analytics.html in your Jekyll site.

Overriding GitHub-generated URLs

Templates often rely on URLs supplied by GitHub such as links to your repository or links to download your project. If you'd like to override one or more default URLs:

Look at the template source to determine the name of the variable. It will be in the form of {{ site.github.zip_url }}.

Specify the URL that you'd like the template to use in your site's _config.yml. For example, if the variable was site.github.url, you'd add the following:

github:
  zip_url: http://example.com/download.zip
  another_url: another value

When your site is built, Jekyll will use the URL you specified, rather than the default one provided by GitHub.

Note: You must remove the site. prefix, and each variable name (after the github.) should be indent with two space below github:.

For more information, see the Jekyll variables documentation.

Roadmap

See the open issues for a list of proposed features (and known issues).

Project philosophy

The Slate theme is intended to make it quick and easy for GitHub Pages users to create their first (or 100th) website. The theme should meet the vast majority of users' needs out of the box, erring on the side of simplicity rather than flexibility, and provide users the opportunity to opt-in to additional complexity if they have specific needs or wish to further customize their experience (such as adding custom CSS or modifying the default layout). It should also look great, but that goes without saying.

Contributing

Interested in contributing to Slate? We'd love your help. Slate is an open source project, built one contribution at a time by users like you. See the CONTRIBUTING file for instructions on how to contribute.

Previewing the theme locally

If you'd like to preview the theme locally (for example, in the process of proposing a change):

  1. Clone down the theme's repository (git clone https://github.com/pages-themes/slate)
  2. cd into the theme's directory
  3. Run script/bootstrap to install the necessary dependencies
  4. Run bundle exec jekyll serve to start the preview server
  5. Visit localhost:4000 in your browser to preview the theme

Running tests

The theme contains a minimal test suite, to ensure a site with the theme would build successfully. To run the tests, simply run script/cibuild. You'll need to run script/bootstrap once before the test script will work.

Download Details:

Author: Pages-themes
Source Code: https://github.com/pages-themes/slate 
License: CC0-1.0 license

#jekyll #pages #theme #githubpages 

Slate: A Jekyll Theme for GitHub Pages
Gordon Matlala

Gordon Matlala

1667421540

Jekyll Theme for Creating Project Documentation Websites

Jekyll Doc Theme

Go to the website for detailed information and demo.

Running locally

You need Ruby and gem before starting, then:

# install bundler
gem install bundler

# clone the project
git clone https://github.com/aksakalli/jekyll-doc-theme.git
cd jekyll-doc-theme

# install dependencies
bundle install

# run jekyll with dependencies
bundle exec jekyll serve

Theme Assets

As of the move to support Github Pages a number of files have been relocated to the /asset folder.

  • css/
  • fonts/
  • img/
  • js/
  • 404.html
  • allposts.html
  • search.json

Docker

Alternatively, you can deploy it using the multi-stage Dockerfile that serves files from Nginx for better performance in production.

Build the image for your site's JEKYLL_BASEURL:

docker build --build-arg JEKYLL_BASEURL="/your-base/url" -t jekyll-doc-theme .

(or leave it empty for root: JEKYLL_BASEURL="") and serve it:

docker run -p 8080:80 jekyll-doc-theme

Github Pages

The theme is also available to Github Pages by making use of the Remote Theme plugin:

Gemfile

# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", group: :jekyll_plugins

_config.yml

# Configure the remote_theme plugin with the gh-pages branch
# or the specific tag
remote_theme: aksakalli/jekyll-doc-theme@gh-pages

Theme Assets

Files from your project will override any theme file with the same name. For example, the most comment use case for this, would be to modify your sites theme or colors. To do this, the following steps should be taken:

  1. Copy the contents of the aksakalli/jekyll-doc-theme/asset/css/main.scss to your own project (maintaining folder structure)
  2. Modify the variables you wish to use prior to the import statements, for example:
// Bootstrap variable overrides
$grid-gutter-width: 30px !default;
$container-desktop: (900px + $grid-gutter-width) !default;
$container-large-desktop: (900px + $grid-gutter-width) !default;

@import // Original import statement
  {% if site.bootwatch %}
    "bootswatch/{{site.bootwatch | downcase}}/variables",
  {% endif %}

  "bootstrap",

  {% if site.bootwatch %}
    "bootswatch/{{site.bootwatch | downcase}}/bootswatch",
  {% endif %}

  "syntax-highlighting",
  "typeahead",
  "jekyll-doc-theme"
;

// More custom overrides.
  1. Import or override any other theme styles after the standard imports

Projects using Jekyll Doc Theme

Download Details:

Author: Aksakalli
Source Code: https://github.com/aksakalli/jekyll-doc-theme 
License: MIT license

#jekyll #docs #theme #sass #bootstrap 

Jekyll Theme for Creating Project Documentation Websites
Gordon Matlala

Gordon Matlala

1667417700

Nef: Steroids for Xcode Playgrounds

nef, short for Nefertiti, mother of Ankhesenamun, is a toolset to ease the creation of documentation in the form of Xcode Playgrounds. It provides compile-time verification of documentation, exports it in Markdown format that can be consumed by Jekyll to generate websites, and export Carbon snippets for a given Xcode Playground.

nef is inspired by ΛNK for Kotlin and tut for Scala.

Features

💡 Eases the creation of Xcode Playgrounds with support for third party libraries.

💡 Compiles Xcode Playgrounds with support for 3rd-party libraries from the command line.

💡 Builds a Playground Book for iPad with external dependencies defined in a Swift Package.

💡 Generates Markdown project from nef Playground.

💡 Generates Markdown files that can be consumed from Jekyll to create a microsite.

💡 Export Carbon code snippets for a given nef Playground.

💻 Installation

📟 Using Homebrew (preferred)

➜ brew install nef

It will warn you if there is a missing dependency and will provide guidance to install it.

 

📦 Using Swift Package Manager

nef can be consumed as a library in your macOS project.

.package(url: "https://github.com/bow-swift/nef.git", from: "{version}")

It is an excellent option if you want to use all nef features in your macOS app, even to build new tooling on top of nef.

You can read more about how to use nef library in the nef site.

🔌 Using Xcode Editor Extension

Some of nef features can be used directly in Xcode as an Extension. You can install it directly from App Store or downloading the last binary from the releases section.

📲 Using your iPad

You can create Swift Playgrounds -together with third-party libraries- directly in your iPad using the app nef Playgrounds.

Using a GitHub badge

You can create a nef badge for your GitHub repository, and let users try your project in their iPads.

bow Playground

Usage

📃 Creating a nef Playground

Xcode Playgrounds are a nice tool for prototyping and trying new concepts. However, third party libraries support is a bit cumbersome to add. One of the goals of nef is to make the creation of an Xcode Playground easier with support for one or more libraries.

By default, nef can create an Xcode Playground with support for Bow, the Functional Programming companion library for Swift.

➜ nef playground

And you can use the following option to specify the name for the nef Playground that you are creating:

➜ nef playground --output ~/Desktop --name LatestBowProject

It will create an Xcode project with support for the latest available version of Bow, named LatestBowProject in your ~/Desktop. If you open this nef playground, you will find an Xcode Playground where you can import Bow or any of its modules, and start trying some of its features.

By default, nef playground will be created for iOS platform. If you need to change it, you can use the --platform option.

➜ nef playground --platform osx

If you need to take advantage of nef in your Xcode Playgrounds, you can transform your Xcode Playground into a nef Playground using the following command:

➜ nef playground --playground <Xcode Playground>

Where <Xcode Playground> is the path to your Xcode Playground.

📣 You can create a nef Playground compatible with any different Bow version, branch or commit; even third-party dependencies

Note: The next options are mutually exclusive.

  • --bow-version <x.y.z>: Specify the version of Bow that you want to use in the project. This option lets you test an old version of the library in an Xcode Playground. Example:
➜ nef playground --name OldBowProject --bow-version 0.3.0
  • --bow-branch <branch name>: Specify the branch of Bow that you want to use in the project. This option lets you test features of Bow that are still in development in a branch that has not been merged or released yet. Example:
➜ nef playground --name BranchBowProject --bow-branch master
  • --bow-commit <commit hash>: Specify the commit hash of Bow that you want to use in the project. This option lets you test features of Bow exactly at the moment you need, released or not. Example:
➜ nef playground --name CommitBowProject --bow-commit e70c739067be1f5700f8b692523e1bb8931c7236
  • --podfile <podfile>: Specify a Podfile with your own dependencies. This option lets you create a Playground with support for other libraries. Create a Podfile listing your dependencies and pass it to nef. Example:

Your Podfile, located in ./folder/dependencies:

target 'MyPodsProject' do
  platform :osx, '10.14'
  use_frameworks!

  pod 'Bow', '~> 0.3.0'
end

➜ nef playground --name MyPodsProject --podfile ./folder/dependencies/Podfile
  • --cartfile <cartfile>: Specify a Cartfile with your dependencies. Create a Cartfile listing your dependencies and pass it to nef. Example:

Your Cartfile, located in ./folder/dependencies:

github "bow-swift/Bow"

➜ nef playground --name MyCarthageProject --cartfile ./folder/dependencies/Cartfile

🔨 Compiling a nef Playground

Xcode lets you check for correctness of your Xcode Playground and run it. However, Apple does not provide us commands to compile an Xcode Playground, as they do for building Xcode projects. It is particularly useful in Continuous Integration when you want to verify that your playgrounds are not broken when the libraries you depend on are updated. nef has an option to compile a nef Playground. To do this, you can run the following command:

➜ nef compile --project <nef playground>

If you need to transform your Xcode Playground into a nef Playground you can check Creating a nef Playground section.

Where <nef playground> is the path to nef Playground where your playgrounds are located. Also, you can use the following option with this command:

  • --use-cache: Use cached dependencies if it is possible, in another case, it will download them. Example:
➜ nef compile --project <nef playground> --use-cache

You can also clean the result of the compilation:

➜ nef clean --project <nef playground>

📲 Creating a Playground Book

Swift Playgrounds is a revolutionary app that makes possible to write Swift code on an iPad. In the latest updates, Swift Playgrounds 3.x has added a new feature: UserModules; it lets you include swift code and make it available across multiple chapters like modules.

nef takes advantage of these new possibilities and advancements in Swift Package Manager to build a Playground Book with external dependencies from a Swift Package specification.

Given a Package.swift like the next one:

// swift-tools-version:5.2

import PackageDescription

let package = Package(
    name: "BowProject",
    products: [
        .library(name: "BowProject", targets: ["nef"])
    ],
    dependencies: [
        .package(url: "https://github.com/bow-swift/bow.git", from: "0.8.0"),
    ],
    targets: [
        .target(name: "nef", dependencies: ["Bow"])
    ]
)

you can run the following command:

➜ nef ipad --name PlaygroundName --package Package.swift --output ~/Desktop

It will create a Playground Book (PlaygroundName) with support for the external dependencies and save it in ~/Desktop

Options:

  • --name: the name for the Playground Book to build.
  • --package: path to the Swift Package specification.
  • --output: path where the resulting Playground Book will be generated.

🔖 Generating a Markdown project

Xcode Playgrounds let you write comments in Markdown format using the symbols //: for single line comments, or /*: */ for multiline comments. Inside these comments, you can use any Markdown syntax; an example:

/*:
 # This is a heading 1

 This is regular text. *This is bold text*. [This is a link](http://bow-swift.io).
 */
protocol MyProtocol {}

//: ## This is a single line heading 2

It makes Xcode Playgrounds the proper tool to write an article with compilable examples. The command provided by nef to generate the Markdown files is:

➜ nef markdown --project <nef playground> --output <path>

Options:

  • --project: Path to your nef Playground.
  • --output: Path where the resulting Markdown project will be generated.

🌐 Generating Markdown files for Jekyll

As you can write comments in Markdown in Xcode Playgrounds, this makes it very suitable to write documentation with compilable examples. Leveraging this, nef can create Markdown files that can be consumed from Jekyll to generate a microsite. The command to do this is:

➜ nef jekyll --project <nef playground> --output <path> --main-page <main-page>

Options:

  • --project: Path to your nef Playground.
  • --output: Path where the resulting Markdown files will be generated.
  • --main-page: Optional. Path to 'README.md' file to be used as the index page of the generated microsite.

📣 How to setup a nef Playgroud for Jekyll?

nef finds all the Xcode Playgrounds in a nef Playground. Each playground is considered a section in the generated microsite structure. For each page in a playground, an entry in the corresponding section is created. The page is transformed from Swift to Markdown using the syntax described above. As a result, a directory structure matching the nef Playground structure is generated, together with a sidebar.yml that can be used as a menu in Jekyll.

nef adds some commands to modify the Markdown transformation process. All nef commands are included as Swift comments. They begin with // nef:begin: and end with // nef:end. The supported commands are:

  • header: It lets you add metadata to a playground page to be consumed by Jekyll. You must provide the layout that this page will use in Jekyll. The remaining attributes are optional, and you may include any of them according to your Jekyll configuration. nef will take care of the permalinks as well. Example (at the beginning of the playground page):
// nef:begin:header
/*
  layout: docs
*/
// nef:end
  • hidden: It lets you hide a portion of your playground in the output Markdown file. It is useful to hide imports or supporting utility code to make an example work. Example:
// nef:begin:hidden
import Bow // This will be hidden in the Markdown file
// nef:end

struct Person {} // This will be present in the Markdown file

🌁 Exporting Carbon code snippets

Xcode Playgrounds are a great place for prototyping and trying new concepts. Oftentimes we want to share some Swift snippets. Carbon is a cool tool for this, and nef nicely integrates with it. You can take your nef Playground, write several pieces of code, and keep it verified. Later, you can export all your code snippets with the next command:

➜ nef carbon --project <nef playground> --output <path>

Options:

  • --project: Path to your nef Playground.
  • --output: Path where the resulting Carbon snippets will be generated.

📣 You can customize the output with the next commands

CommandDescriptionFormatOptionsDefault
--backgroundBackground color applied to imagehexadecimal #AABBCC, #AABBCCDD or predefined colors nef bow white 
green blue yellow 
orange		nef
--themeCarbon's theme to be appliedStringbase16-dark blackboard cobalt duotone-dark dracula hopscotch lucario material monokai night-owl nord oceanic-next one-dark panda-syntax paraiso-dark seti shades-of-purple synthwave-84 tomorrow-night-bright twilight verminal vscode zenburndracula
--sizeExport file dimensionsNumber[1, 5]2
--fontFont typeStringfiraCode hack inconsolata iosevka monoid anonymousPro sourceCodePro darkMono droidMono fantasqueMono ibmPlexMono spaceMono ubuntuMonofiraCode
--show-linesshows/hides number of lines in code snippetBooltrue falsetrue
--show-watermarkshows/hides watermark in code snippetBooltrue falsetrue

Example of use

If we have a project created by nef, and an Xcode playground with the next content:

let example = "This is an example"
print("nef is super cool: \(example)")

// nef is super cool: This is an example

Running the following command, we will customize the background color to #d54048 bow, hide the number of lines, and set the export file to size 3:

➜ nef carbon --project . --output ~/Desktop/nef-carbon --background bow --size 3 --show-lines false

❤️ Contributing to the project

You can contribute in different ways to make nef better:

  • File an issue if you encounter a bug or malfunction in nef.
  • Suggest a new use case or feature for nef.
  • Open a Pull Request fixing a problem or adding new functionality. You can check the Issues to see some of the pending tasks.
  • Discuss with us in the Gitter channel for Bow about all the above.

How to run the project

Open project/nef.xcodeproj in Xcode 11 (or newer) and you are ready to go. nef uses the [Swift Package Manager] to handle its dependencies - they will be resolving automatically from Xcode.

How to run the documentation project

  • Go to main directory where you can find the nef Playground Documentation.app.
  • Run nef compile --project Documentation.app to set up the project with its dependencies.
  • Open Documentation.app

For further information, refer to our Contribution guidelines.

Download Details:

Author: Bow-swift
Source Code: https://github.com/bow-swift/nef 
License: View license

#jekyll #swift #functionalprogramming 

Nef: Steroids for Xcode Playgrounds
Gordon Matlala

Gordon Matlala

1667413800

Kmeans_pytorch: Kmeans using Pytorch

K Means using PyTorch

PyTorch implementation of kmeans for utilizing GPU

Getting Started


import torch
import numpy as np
from kmeans_pytorch import kmeans

# data
data_size, dims, num_clusters = 1000, 2, 3
x = np.random.randn(data_size, dims) / 6
x = torch.from_numpy(x)

# kmeans
cluster_ids_x, cluster_centers = kmeans(
    X=x, num_clusters=num_clusters, distance='euclidean', device=torch.device('cuda:0')
)

see example.ipynb for a more elaborate example

Requirements

  • PyTorch version >= 1.0.0
  • Python version >= 3.6

Installation

install with pip:

pip install kmeans-pytorch

Installing from source

To install from source and develop locally:

git clone https://github.com/subhadarship/kmeans_pytorch
cd kmeans_pytorch
pip install --editable .

CPU vs GPU

see cpu_vs_gpu.ipynb for a comparison between CPU and GPU

Notes

  • useful when clustering large number of samples
  • utilizes GPU for faster matrix computations
  • support euclidean and cosine distances (for now)

Credits

  • This implementation closely follows the style of this
  • Documentation is done using the awesome theme jekyllbook

Download Details:

Author: Subhadarship
Source Code: https://github.com/subhadarship/kmeans_pytorch 
License: MIT license

#jekyll #pytorch #githubpages #docs #gpu 

Kmeans_pytorch: Kmeans using Pytorch
Gordon Matlala

Gordon Matlala

1667409960

Neumorphism Designed Jekyll Theme for Personal Websites

Neumorphism

Neumorphism designed Jekyll theme for personal websites, portfolios and resumes.

About The Project

Project Screenshot

This is a personal website built with Jekyll and hosted on Github Pages, which is based on the new Neumorphism design trend and was developed with a mobile-first approach. This can be used by developers, who want to showcase their resume and portfolio. If you want to use this for your own website, fork this repository and then refer to personalize and customize.

Built With

Features

Getting Started

To get a local copy up and running follow these simple steps.

The commands and instructions I provide are for MacOS - please look up the specific commands for your OS on your own.

Prerequisites

brew install node

If you need to switch between Node versions regurlarly, I would recommend to install Node via Node Version Manager.

gem install bundler jekyll

For more information, refer to this.

npm install -g yarn

Installation

Recommended way: If you want to contribute to this theme or open issues due to problems implementing this on your own, I would recommend forking the repository directly. This makes it easier for me to solve open issues and questions or check pull requests.

1.1: Fork the repository (using the Fork button at the top) and then clone the repository

# Replace {YOUR_USERNAME} with your actual username
git clone https://github.com/{YOUR_USERNAME}/neumorphism.git

or

1.2: Create your own repository (using the green Use this template button at the top) and then clone the repository

# Replace {YOUR_USERNAME}, {YOUR_REPOSITORY} with the actual values
git clone https://github.com/{YOUR_USERNAME}/{YOUR_REPOSITORY}.git

2: Change directory into neumorphism

cd neumorphism

3: Install dependencies

yarn
bundle install

Usage

  • Run and develop locally with live server at http://localhost:4000, this will also build production-ready JS and SCSS assets with every change
gulp
  • After committing and pushing, see the Settings page of your repository to see where your site is published at via Github Pages.

Personalize and Customize

_config.yml

Edit _config.yml to personalize your site. For documentation, refer to docs/config.md.

Github Metadata Plugin

If you want to automatically have your Github repositories pulled for the Open Source Projects section, then you also need to authenticate yourself for the Github Metadata plugin to work.

You need to generate a new personal access token on GitHub:

  • Go to the Github Token site
  • Select the scope public_repository, and add a description.
  • Confirm and save the settings. Copy the token you see on the page.
  • Create a .env file inside your repository and add your generated JEKYLL_GITHUB_TOKEN:
JEKYLL_GITHUB_TOKEN=0YOUR0GENERATED0TOKEN0

To complete the configuration for the Github Metadata plugin, you also need to change the value of repository inside _config.yml. After this, you should the Github Metadata plugin should work properly.

For optimal results, you should make sure, that every Github project, you want included on this portfolio, has added following informations on Github:

  • Description
  • Homepage link, if there is a live version of it
  • Topics

Example: Github Repository Information Example

_data/*.yml

Edit files inside _data to add information to the portfolio. For documentation, refer to docs/data.md.

Particles.js

Edit assets/particles.json to customize the landing page backgorund animation. For more information, refer to this.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Acknowledgements

Download Details:

Author: longpdo
Source Code: https://github.com/longpdo/neumorphism 
License: MIT license

#jekyll #theme #template #githubpages 

Neumorphism Designed Jekyll Theme for Personal Websites
Gordon Matlala

Gordon Matlala

1667406120

Understand and Fix Your Static Website Trailing Slash Issues!

Trailing Slash Guide

Have trailing slash problems after deploying a static website in production?

This repo explains factually the behavior of:

We also suggest some possible solutions

Intro

Let's get more familiar with trailing slash issues.

Common problems:

  • SEO/perf issues: when browsing /myPath, your host redirects to /myPath/
  • 404 issues: relative link such as <a href="otherPath"> are resolved differently (/otherPath or /myPath/otherPath depending on the presence/absence of a trailing slash
  • UX issues: your host adds a trailing slash, and later your single-page-application frontend router removes it, leading to a confusing experience and flickering url

Causes:

  • static site generators can emit different files for the same path /myPath: /myPath.html or /myPath/index.html (the later can lead to an additional trailing slash)
  • host providers all have a different behavior when serving static files, there is no standard

Summary

Considering this static site:

static
│
├── file.html
│
├── folder
│   └── index.html
│
├── both.html
└── both
    └── index.html

Behavior of various static hosting providers:

HostSettingsUrl/file/file//file.html/folder/folder//folder/index.html/both/both//both.html/both/index.html
GitHub Pages link✅💢 404✅➡️ /folder/✅✅✅✅✅✅
NetlifyDefaultlink✅➡️ /file✅➡️ /folder/✅✅✅➡️ /both✅✅
NetlifyPretty Urls onlink✅➡️ /file✅➡️ /folder/✅✅✅➡️ /both✅✅
NetlifyPretty Urls offlink✅✅✅✅✅✅✅✅✅✅
VercelDefaultlink💢 404💢 404✅✅✅✅✅✅✅✅
VercelcleanUrls=false trailingSlash=undefinedlink💢 404💢 404✅✅✅✅✅✅✅✅
VercelcleanUrls=false trailingSlash=falselink💢 404💢 404✅✅➡️ /folder✅✅➡️ /both✅✅
VercelcleanUrls=false trailingSlash=truelink💢 404💢 404✅➡️ /folder/✅✅➡️ /both/✅✅✅
VercelcleanUrls=true trailingSlash=undefinedlink💢 404💢 404✅✅✅✅✅✅✅✅
VercelcleanUrls=true trailingSlash=falselink✅➡️ /file➡️ /file✅➡️ /folder➡️ /folder✅➡️ /both➡️ /both➡️ /both
VercelcleanUrls=true trailingSlash=truelink➡️ /file/✅➡️ /file/➡️ /folder/✅➡️ /folder/➡️ /both/✅➡️ /both/➡️ /both/
Cloudflare Pages link✅➡️ /file➡️ /file➡️ /folder/✅➡️ /folder/✅✅➡️ /both➡️ /both/
Render link✅✅✅✅✅✅✅✅✅✅
Azure Static Web Apps link✅➡️ /file✅✅✅✅✅✅✅✅

Help Wanted

Let's keep this resource up-to-date, and make it exhaustive together.

Download Details:

Author: Slorber
Source Code: https://github.com/slorber/trailing-slash-guide 
License: MIT license

#jekyll #react #generator #nextjs #static 

Understand and Fix Your Static Website Trailing Slash Issues!
Gordon Matlala

Gordon Matlala

1667402340

Jekyll-toc: Jekyll Plugin Which Generates A Table Of Contents

jekyll-toc

Jekyll Plugin Which Generates A Table Of Contents

Installation

Add jekyll-toc plugin in your site's Gemfile, and run bundle install.

gem 'jekyll-toc'

Add jekyll-toc to the gems: section in your site's _config.yml.

plugins:
  - jekyll-toc

Set toc: true in posts for which you want the TOC to appear.

---
layout: post
title: "Welcome to Jekyll!"
toc: true
---

Usage

There are three Liquid filters, which can be applied to HTML content, e.g. the Liquid variable content available in Jekyll's templates.

Basic Usage

toc filter

Add the toc filter to your site's {{ content }} (e.g. _layouts/post.html).

{{ content | toc }}

This filter places the TOC directly above the content.

Advanced Usage

If you'd like separated TOC and content, you can use {% toc %} tag (or toc_only filter) and inject_anchors filter.

{% toc %} tag / toc_only filter

Generates the TOC itself as described below. Mostly useful in cases where the TOC should not be placed immediately above the content but at some other place of the page, i.e. an aside.

<div>
  <div id="table-of-contents">
    {% toc %}
  </div>
  <div id="markdown-content">
    {{ content }}
  </div>
</div>

:warning: {% toc %} Tag Limitation

{% toc %} works only for Jekyll Posts and Jekyll Collections. If you'd like to use {% toc %} except posts or collections, please use toc_only filter as described below.

<div>
  <div id="table-of-contents">
    {{ content | toc_only }}
  </div>
  <div id="markdown-content">
    {{ content | inject_anchors }}
  </div>
</div>

inject_anchors filter

Injects HTML anchors into the content without actually outputting the TOC itself. They are of the form:

<a class="anchor" href="#heading1-1" aria-hidden="true">
  <span class="octicon octicon-link"></span>
</a>

This is only useful when the TOC itself should be placed at some other location with the toc_only filter.

Generated HTML

jekyll-toc generates an unordered list by default. The HTML output is as follows.

<ul id="toc" class="section-nav">
  <li class="toc-entry toc-h1"><a href="#heading1">Heading.1</a>
    <ul>
      <li class="toc-entry toc-h2"><a href="#heading1-1">Heading.1-1</a></li>
      <li class="toc-entry toc-h2"><a href="#heading1-2">Heading.1-2</a></li>
    </ul>
  </li>
  <li class="toc-entry toc-h1"><a href="#heading2">Heading.2</a>
    <ul>
      <li class="toc-entry toc-h2"><a href="#heading2-1">Heading.2-1</a>
        <ul>
          <li class="toc-entry toc-h3"><a href="#heading2-1-1">Heading.2-1-1</a></li>
          <li class="toc-entry toc-h3"><a href="#heading2-1-2">Heading.2-1-2</a></li>
        </ul>
      </li>
      <li class="toc-entry toc-h2"><a href="#heading2-2">Heading.2-2</a></li>
    </ul>
  </li>
</ul>

screenshot

Customization

jekyll-toc is customizable on _config.yml.

Default Configuration

# _config.yml
toc:
  min_level: 1
  max_level: 6
  ordered_list: false
  no_toc_section_class: no_toc_section
  list_id: toc
  list_class: section-nav
  sublist_class: ''
  item_class: toc-entry
  item_prefix: toc-

TOC levels

# _config.yml
toc:
  min_level: 2 # default: 1
  max_level: 5 # default: 6

The default heading range is from <h1> to <h6>.

Enable TOC by default

You can enable TOC by default with Front Matter Defaults:

# _config.yml
defaults:
  - scope:
      path: ""
    values:
      toc: true

Skip TOC

The heading is ignored in the toc by adding no_toc class.

<h1>h1</h1>
<h1 class="no_toc">This heading is ignored in the TOC</h1>
<h2>h2</h2>

Skip TOC Sectionally

The headings are ignored inside the element which has no_toc_section class.

<h1>h1</h1>
<div class="no_toc_section">
  <h2>This heading is ignored in the TOC</h2>
  <h3>This heading is ignored in the TOC</h3>
</div>
<h4>h4</h4>

Which would result in only the <h1> & <h4> within the example being included in the TOC.

The class can be configured on _config.yml:

# _config.yml
toc:
  no_toc_section_class: exclude # default: no_toc_section

Configuring multiple classes are allowed:

# _config.yml
toc:
  no_toc_section_class:
    - no_toc_section
    - exclude
    - your_custom_skip_class_name

CSS Styling

The toc can be modified with CSS. The sample CSS is the following.

.section-nav {
  background-color: #fff;
  margin: 5px 0;
  padding: 10px 30px;
  border: 1px solid #e8e8e8;
  border-radius: 3px;
}

screenshot

Each TOC li entry has two CSS classes for further styling. The general toc-entry is applied to all li elements in the ul.section-nav.

Depending on the heading level each specific entry refers to, it has a second CSS class toc-XX, where XX is the HTML heading tag name. For example, the TOC entry linking to a heading <h1>...</h1> (a single # in Markdown) will get the CSS class toc-h1.

Custom CSS Class and ID

You can apply custom CSS classes to the generated <ul> and <li> tags.

# _config.yml
toc:
  list_id: my-toc-id # Default: "toc"
  list_class: my-list-class # Default: "section-nav"
  sublist_class: my-sublist-class # Default: no class for sublists
  item_class: my-item-class # Default: "toc-entry"
  item_prefix: item- # Default: "toc-":

Using Unordered/Ordered lists

By default the table of contents will be generated as an unordered list via <ul></ul> tags. This can be configured to use ordered lists instead <ol></ol>. This can be configured in _config.yml:

# _config.yml
toc:
  ordered_list: true # default is false

In order to change the list type, use the list-style-type css property. Add a class to the sublist_class configuration to append it to the ol tags so that you can add the list-style-type property.

Example

# _config.yml
toc:
  ordered_list: true
  list_class: my-list-class
  sublist_class: my-sublist-class

.my-list-class {
  list-style-type: upper-alpha;
}

.my-sublist-class: {
  list-style-type: lower-alpha;
}

This will produce:

screenshot

Alternative Tools

Download Details:

Author: Toshimaru
Source Code: https://github.com/toshimaru/jekyll-toc 
License: MIT license

#jekyll #ruby #gem 

Jekyll-toc: Jekyll Plugin Which Generates A Table Of Contents