From 4a7b406615fa603029fcffa1c1e8052330da916b Mon Sep 17 00:00:00 2001 From: Youssef Raafat Date: Sat, 25 Jan 2020 14:55:36 +0200 Subject: [PATCH] Update Documentation --- docs/_config.yml | 28 +++++------ .../documentation/partials/02-installation.md | 37 +++++++++++++- .../02-installation/01-github-pages.md | 50 ------------------- .../partials/02-installation/02-fork.md | 9 ---- .../partials/03-customization.md | 20 +++++++- portfolyou-jekyll-theme.gemspec | 2 +- 6 files changed, 67 insertions(+), 79 deletions(-) delete mode 100644 docs/documentation/partials/02-installation/01-github-pages.md delete mode 100644 docs/documentation/partials/02-installation/02-fork.md diff --git a/docs/_config.yml b/docs/_config.yml index 560bd00b6..76124d417 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,14 +1,12 @@ ### Site Settings ### title : portfolYOU -description : >- # >- means to ignore newlines until "url:" +description : >- "I turn coffee :coffee: into code, use tabs over spaces and never broke production." - -url : "" # base hostname & protocol for your site (e.g. http://example.com) -baseurl : "/portfolYOU" # subpath of your site (e.g. /blog) [IMPORTANT: use "" if your are hosting at https://username.github.io directly] -repository : YoussefRaafatNasry/portfolYOU # repository metadata on GitHub Pages [know more at https://help.github.com/en/articles/repository-metadata-on-github-pages] -remote_theme : YoussefRaafatNasry/portfolYOU # uncomment this if you are using it as a remote theme +baseurl : "/portfolYOU" # Change to empty quotes if you are hosting your site at .github.io directly +repository : YoussefRaafatNasry/portfolYOU # Change to /.github.io (or remove it if you don't need remote projects) +remote_theme : YoussefRaafatNasry/portfolYOU ### Plugins ### @@ -17,11 +15,11 @@ plugins: ### Navbar Settings ### -nav_exclude: # Pages with the following paths will be excluded from navbar +nav_exclude: # The following paths are excluded from navbar - pages/tags.html - pages/404.html - pages/index.md - - documentation/partials/** + - documentation/partials/** # For Documentation Only ### Author Info ### @@ -56,8 +54,8 @@ collections: projects: output: true permalink: /projects/:name - elements: - output: true + elements: # For Documentation Only + output: true # For Documentation Only ### Defaults for collections ### @@ -67,11 +65,11 @@ defaults: type: "projects" values: layout: "page" - - scope: - path: "" - type: "elements" - values: - layout: "element" + - scope: # For Documentation Only + path: "" # For Documentation Only + type: "elements" # For Documentation Only + values: # For Documentation Only + layout: "element" # For Documentation Only ### Exclude from processing ### diff --git a/docs/documentation/partials/02-installation.md b/docs/documentation/partials/02-installation.md index cf23ccced..a0f506f1b 100644 --- a/docs/documentation/partials/02-installation.md +++ b/docs/documentation/partials/02-installation.md @@ -1,8 +1,41 @@ ## Installation +The following steps demonstrate how to use portfolYOU as **GitHub Pages remote theme**. + +1. [Download][download] portfolYOU as .zip from official [repo][repo] then extract it. +1. Rename **`portfolYOU-master/`** to **`.github.io/`** +1. Remove everything **except** the **`docs/`** directory. +1. Lift up the **`docs/`** directory's content to the root directory _(i.e move them to **`.github.io/`**)_. +1. Remove **documentation** stuff: + - **`_elements/`** + - **`documentation/`** + - **`_config.yml`** : any line commented as `# For Documentation Only` + +1. Your directory structure should be: + + ```tree + .github.io/ + ├── _data/ + ├── _posts/ + ├── _projects/ + ├── pages/ + ├── _config.yml + ├── .gitignore + └── Gemfile + ``` + +1. Update **`_config.yml`** with your data _(follow the comments for more help)_. +1. Update your site content (posts, projects and about page). +1. Finally, test portfolYOU [locally][locally] then [publish][publish] it to [GitHub Pages][gh-pages]. +1. _[Optional]_ To use a specific [version][versions] of portfolYOU _(defaults to latest version)_: + + ```yml + remote_theme: YoussefRaafatNasry/portfolYOU@v1.0.0 + ``` + [repo]: {{ site.github.repository_url }} -[fork]: {{ site.github.repository_url }}/fork [download]: {{ site.github.zip_url }} [versions]: {{ site.github.releases_url }} [locally]: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/ -[gh-pages]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ +[publish]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ +[gh-pages]: https://pages.github.com/ diff --git a/docs/documentation/partials/02-installation/01-github-pages.md b/docs/documentation/partials/02-installation/01-github-pages.md deleted file mode 100644 index 24c2b6915..000000000 --- a/docs/documentation/partials/02-installation/01-github-pages.md +++ /dev/null @@ -1,50 +0,0 @@ -#### As a GitHub Pages remote theme - -1. [Download][download] portfolYOU as .zip from official [repo][repo] then extract the files. -1. Delete unnecessary files and folders: `README.md`, `CONTRIBUTING.md`, `LICENSE`, `docs/` -1. Delete theme directories, _as they will be included remotely_ : `_includes/`, `_layouts/`, `_sass/`, `assets/` -1. Delete `Gemfile` and `.gitignore` if you aren't going to set up the theme [locally]. -1. Your directory structure should be looking something like this: - - ```tree - your_site_name/ - ├── _data/ - │ ├── other-skills.yml - │ ├── programming-skills.yml - │ ├── social-media.yml - │ └── timeline.yml - ├── _posts/ - │ ├── YYYY-MM-DD-post-1.md - │ ├── .... - │ └── YYYY-MM-DD-post-n.md - ├── _projects/ - │ ├── project-1.md - │ ├── .... - │ └── project-n.md - ├── blog/ - │ ├── index.html - │ └── tags.html - ├── pages/ - │ ├── about.md - │ └── projects.html - ├── _config.yml - ├── 404.html - ├── index.html - └── search.json - ``` - -1. Uncomment the following line in `_config.yml`: - - ```yaml - remote_theme: YoussefRaafatNasry/portfolYOU - ``` - - to use a specific [version][versions] of portfolYOU: - - ```yaml - remote_theme: YoussefRaafatNasry/portfolYOU@v1.0.0 - ``` - -1. Replace `baseurl: "/portfolYOU"` with `baseurl: ""` if your are hosting the site at `username.github.io` directly. -1. Change other configuration options in `_config.yml` depending on your needs. -1. Set up portfolYOU [locally] or publish it to [GitHub Pages][gh-pages]. diff --git a/docs/documentation/partials/02-installation/02-fork.md b/docs/documentation/partials/02-installation/02-fork.md deleted file mode 100644 index 7ae464849..000000000 --- a/docs/documentation/partials/02-installation/02-fork.md +++ /dev/null @@ -1,9 +0,0 @@ -#### As a Fork - -1. [Fork][fork] the [repo][repo]. -1. Clone your fork. -1. Delete unwanted **sections**. -1. Modify and edit files' contents upon your needs. -1. Change configuration options in `_config.yml` depending on your needs. -1. Commit and push changes to your fork. -1. Set up portfolYOU [locally] or publish it to [GitHub Pages][gh-pages]. diff --git a/docs/documentation/partials/03-customization.md b/docs/documentation/partials/03-customization.md index 87fad2a92..6a0622acd 100644 --- a/docs/documentation/partials/03-customization.md +++ b/docs/documentation/partials/03-customization.md @@ -1,4 +1,20 @@ ## Customization -When using portfolYOU as a theme means you can take advantage of the file overriding method. This allows you to overwrite any file in this theme with your own custom file, simply by matching the file name and path. The most common example of this would be if you want to add your own styles or change the favicon. -To change the favicon for example just generate your own using [favicon](https://favicon.io/) or any other tool. Copy your new `favicon.ico` file into your own project with the same file path `assets/favicon.ico`. +Simply **override** the file you want to change by matching the **same file name and path**. + +**Example 1:** New Favicon + +1. Generate your own using [favicon](https://favicon.io/) or any other tool. +1. Copy your new `favicon.ico` file into your own project with the same file path **`assets/favicon.ico`**. + +**Example 2:** Custom Style + +1. Create **`assets/css/styles.scss`**. +1. Add the following lines: + + ```css + --- + --- + /* Add your custom style here */ + @import "portfolYOU"; + ``` diff --git a/portfolyou-jekyll-theme.gemspec b/portfolyou-jekyll-theme.gemspec index c4a4713f8..e4d9041d2 100644 --- a/portfolyou-jekyll-theme.gemspec +++ b/portfolyou-jekyll-theme.gemspec @@ -1,6 +1,6 @@ Gem::Specification.new do |spec| spec.name = "portfolyou-jekyll-theme" - spec.version = "2.2.1" + spec.version = "2.2.2" spec.authors = ["Youssef Raafat"] spec.email = ["YoussefRaafatNasry@gmail.com"]