Generate social iconsheet during build (jekyll#686)

Merge pull request 686
mariajemaria · Nov 11, 2022 · 0ac17f8 · 0ac17f8
1 parent 41b9769
commit 0ac17f8
Show file tree

Hide file tree

Showing 24 changed files with 113 additions and 140 deletions.
diff --git a/README.md b/README.md
@@ -67,6 +67,8 @@ Refers to snippets of code within the `_includes` directory that can be inserted
   - `custom-head.html` &mdash; Placeholder to allow users to add more metadata to `<head />`.
   - `header.html` &mdash; Defines the site's main header section. By default, pages with a defined `title` attribute will have links displayed here.
   - `social.html` &mdash; Renders social-media icons based on the `minima:social_links` data in the config file.
+  - `social-item.html` &mdash; Template to render individual list-item containing graphic link to configured social-profile.
+  - `social-links/*.svg` &mdash; SVG markup components of supported social-icons.
 
 
 ### Sass
@@ -90,8 +92,8 @@ Refers to various asset files within the `assets` directory.
 
   - `assets/css/style.scss` &mdash; Imports sass files from within the `_sass` directory and gets processed into the theme's
     stylesheet: `assets/css/styles.css`.
-  - `assets/minima-social-icons.svg` &mdash; A composite SVG file comprised of *symbols* related to various social-media icons.
-    This file is used as-is without any processing. Refer [section on social networks](#social-networks) for its usage.
+  - `assets/minima-social-icons.html` &mdash; Imports enabled social-media icon graphic and gets processed into a composite SVG file.
+    Refer [section on social networks](#social-networks) for its usage.
 
 
 ### Plugins
@@ -259,42 +261,64 @@ Minima 2.x    | Minima 3.0
 
 ### Social networks
 
-You can add links to the accounts you have on other sites, with respective icon, by adding one or more of the following options in your config.
-From `Minima-3.0` onwards, the usernames are to be nested under `minima.social_links`, with the keys being simply the social-network's name:
+You can add links to the accounts you have on other sites, with respective icon as an SVG graphic, via the config file.
+From `Minima-3.0` onwards, the social media data is sourced from config key `minima.social_links`. It is a list of key-value pairs, each entry
+corresponding to a link rendered in the footer. For example, to render links to Jekyll GitHub repository and twitter account, one should have:
 
 ```yaml
 minima:
   social_links:
-    twitter: jekyllrb
-    github: jekyll
-    stackoverflow: "11111"
-    dribbble: jekyll
-    facebook: jekyll
-    flickr: jekyll
-    instagram: jekyll
-    linkedin: jekyll
-    pinterest: jekyll
-    telegram: jekyll
-    microdotblog: jekyll
-    keybase: jekyll
-
-    mastodon:
-     - username: jekyll
-       instance: example.com
-     - username: jekyll2
-       instance: example.com
-
-    gitlab:
-     - username: jekyll
-       instance: example.com
-     - username: jekyll2
-       instance: example.com
-
-    youtube: jekyll
-    youtube_channel: UC8CXR0-3I70i1tfPg1PAE1g
-    youtube_channel_name: CloudCannon
+    - { platform: github,  user_url: "https://github.com/jekyll/jekyll" }
+    - { platform: twitter, user_url: "https://twitter.com/jekyllrb" }
 ```
 
+Apart from the necessary keys illustrated above, `title` may also be defined to render a custom link-title. By default, the title is the same
+as `platform`. The `platform` key corresponds to the SVG id of the sprite in the composite file at URL `/assets/minima-social-icons.svg`.
+
+The theme ships with an icon for `rss` and icons of select social-media platforms:
+
+- `devto`
+- `dribbble`
+- `facebook`
+- `flickr`
+- `github`
+- `google_scholar`
+- `instagram`
+- `keybase`
+- `linkedin`
+- `microdotblog`
+- `pinterest`
+- `stackoverflow`
+- `telegram`
+- `twitter`
+- `youtube`
+
+To render a link to a platform not listed above, one should first create a file at path `_includes/social-icons/<PLATFORM>.svg` comprised of
+graphic markup **without the top-level `<svg></svg>`**. The icon is expected to be centered within a viewbox of `"0 0 16 16"`. Then, make an
+entry under key `minima.social_links`.
+
+For example, to render a link to an account of user `john.doe` at platform `deviantart.com`, the steps to follow would be:
+  - Get DeviantArt logo in SVG format.
+  - Using a text-editor, open the downloaded file to inspect if the `viewBox` attribute is defined on the `<svg>` element and is set
+    as `"0 0 16 16" (or similar "square" dimension)`.
+  - If the `viewBox` attribute is non-square or undefined, the graphic *may optionally need* to be edited in a vector graphic editor such as
+    *Inkscape* or *Adobe Illustrator* for properly aligned render on page.
+  - Edit the SVG file in text-editor to delete everything **except** what is contained between `<svg></svg>` and save it into the Jekyll
+    project at path `_includes/social-icons/deviantart.svg`.
+  - Finally, edit the Jekyll config file to enable loading of new icon graphic with:
+    ```yaml
+    minima:
+      social_links:
+        - platform: deviantart  # same as SVG filename.
+          user_url: "https://www.deviantart.com/john.doe"  # URL of profile page.
+          title:  My profile at DeviantArt.com  # Optional. Text displayed on hovering over link.
+    ```
+
+**Notes:**
+- The list of social-links is declarative. List-items are rendered in the order declared in the downstream configuration file and not merged
+  with entries from upstream config file(s) such as theme-config-file or prior local config files.
+- The `user_url` is rendered as given without handling any special characters within.
+
 
 ### Enabling Google Analytics
 

diff --git a/_config.yml b/_config.yml
@@ -16,37 +16,21 @@ minima:
 
   # generate social links in footer
   social_links:
-    twitter: jekyllrb
-    github:  jekyll
-    # devto: jekyll
-    # dribbble: jekyll
-    # facebook: jekyll
-    # flickr:   jekyll
-    # instagram: jekyll
-    # linkedin: jekyll
-    # pinterest: jekyll
-    # youtube: jekyll
-    # youtube_channel: UC8CXR0-3I70i1tfPg1PAE1g
-    # youtube_channel_name: CloudCannon
-    # telegram: jekyll
-    # googleplus: +jekyll
-    # microdotblog: jekyll
-    # keybase: jekyll
-    # google_scholar_id: qc6CJjYAAAAJ
-
-    # Mastodon instances
-    # mastodon:
-    # - username: jekyll
-    #   instance: example.com
-    # - username: jekyll2
-    #   instance: example.com
-
-    # GitLab instances
-    # gitlab:
-    # - username: jekyll
-    #   instance: example.com
-    # - username: jekyll2
-    #   instance: example.com
+    - { platform: devto,          user_url: "https://dev.to/jekyll" }
+    - { platform: dribbble,       user_url: "https://dribbble.com/jekyll" }
+    - { platform: facebook,       user_url: "https://www.facebook.com/jekyll" }
+    - { platform: flickr,         user_url: "https://www.flickr.com/photos/jekyll" }
+    - { platform: github,         user_url: "https://github.com/jekyll/minima" }
+    - { platform: google_scholar, user_url: "https://scholar.google.com/citations?user=qc6CJjYAAAAJ" }
+    - { platform: instagram,      user_url: "https://www.instagram.com/jekyll" }
+    - { platform: keybase,        user_url: "https://keybase.io/jekyll" }
+    - { platform: linkedin,       user_url: "https://www.linkedin.com/in/jekyll" }
+    - { platform: microdotblog,   user_url: "https://micro.blog/jekyll" }
+    - { platform: pinterest,      user_url: "https://www.pinterest.com/jekyll" }
+    - { platform: stackoverflow,  user_url: "https://stackoverflow.com/users/1234567/jekyll" }
+    - { platform: telegram,       user_url: "https://t.me/jekyll" }
+    - { platform: twitter,        user_url: "https://twitter.com/jekyllrb" }
+    - { platform: youtube,        user_url: "https://www.youtube.com/jekyll" }
 
 # If you want to link only specific pages in your header, uncomment
 # this and add the path to the pages in order as they should show up

diff --git a/_includes/social-icons/devto.svg b/_includes/social-icons/devto.svg
diff --git a/_includes/social-icons/dribbble.svg b/_includes/social-icons/dribbble.svg
diff --git a/_includes/social-icons/facebook.svg b/_includes/social-icons/facebook.svg
diff --git a/_includes/social-icons/flickr.svg b/_includes/social-icons/flickr.svg
diff --git a/_includes/social-icons/github.svg b/_includes/social-icons/github.svg
diff --git a/_includes/social-icons/gitlab.svg b/_includes/social-icons/gitlab.svg
diff --git a/_includes/social-icons/google_scholar.svg b/_includes/social-icons/google_scholar.svg
diff --git a/_includes/social-icons/instagram.svg b/_includes/social-icons/instagram.svg
diff --git a/_includes/social-icons/keybase.svg b/_includes/social-icons/keybase.svg
diff --git a/_includes/social-icons/linkedin.svg b/_includes/social-icons/linkedin.svg
diff --git a/_includes/social-icons/mastodon.svg b/_includes/social-icons/mastodon.svg
diff --git a/_includes/social-icons/microdotblog.svg b/_includes/social-icons/microdotblog.svg
diff --git a/_includes/social-icons/pinterest.svg b/_includes/social-icons/pinterest.svg
diff --git a/_includes/social-icons/rss.svg b/_includes/social-icons/rss.svg
diff --git a/_includes/social-icons/stackoverflow.svg b/_includes/social-icons/stackoverflow.svg
diff --git a/_includes/social-icons/telegram.svg b/_includes/social-icons/telegram.svg
diff --git a/_includes/social-icons/twitter.svg b/_includes/social-icons/twitter.svg