Windows 7 Help: GitHub Pages, using subfolders and MD files

I am at level 0 for HTML, CSS, and Jekyll. I do my best to read the documentation but normally I find it’s set up for people who need dry technical quick access to information. Since I am not a web designer I need the verbose, with examples, and example files, and screen shots, kind of instructions.

For example this is the section on creating pages. There is a section on pages, it tells you that you can have subfolders if you have a lot of files, and it goes on and says _site, and then transitions to Named HTML files, permalinks and then static files. Never going over how to use subfolders with MD files.

The other thing is I have no way to know how the page will look or test anything. I use Pycharm for Python and saw it had instructions for setting up Jekyll, only to find out you can’t do that with the free community edition. So to test things I have to make a change, call it test, commit that to github, wait for it to render, then refresh the page, over, and over, and over, and over, until I finally stumble upon something that works. I would love instructions to change that but again I am so new I couldn’t have just the gist of it. I would need screen shots for Windows 7, and detailed install instructions. If it required gitbash, then I’d need to know that’s the program I am using to install something prior to using the command line. Otherwise I’ll go to cmd.exe and try it only to be told that pip is not a recognized command.

This is the temporary site for testing the folders I want to use. I say temporary because I don’t want to add the Theme on GitHub until I know how things work so it doesn’t mess everything up.

I am only able to use a structure where I have a subfolder in root where I add permalink and the name of the page to flatten the URL. The files I want access to are in subfolder, and they contain subfolders as well. They also have files that have the same names. In addition to that I don’t actually want to change the names at all. I just want to set a herf to the file and have it display. I can’t figure out what that URL is supposed to be.

Website URL is: https://tes5edit.github.io/xEdit-Wiki/

What I thought would work was https://tes5edit.github.io/xEdit-Wiki/Fallout3/Redords.md but I get a prompt to download the file and save it rather then seeing the MD file. Then I thought I had to add Front Line data, so I did that but it still doesn’t display the page.

How do I access the files without changing the subfolders or file names. I am happy to set -config.yml, or add other files, or add frontline data to each and every file, or whatever else is needed. I will even make a subfolder called _site if that is needed. However, aside from that the only thing I do not want to change is the folder names or the file names.

How do I set up the site to work with those file?

This is the functional site that I will be applying the jekyll theme to once I know what I am doing.

For example I started at the very beginning and I see that you can add include to the _config.yml. The syntax is listed as “include: [DIR, FILE, …]” which makes no sense since that’s not yaml format. I would think it would look like this.

include:
  - Fallout3
  - Fallout4
  - FalloutNV

Now, I added that but the URL: https://tes5edit.github.io/xEdit-Wiki/Fallout3/Records.md doesn’t work. But it passed for travis.

Then later it shows an example here. The above URL doesn’t work still and it passed travis.

defaults:
  -
    scope:
      path: "FalloutNV"
      type: "pages"
    values:
      layout: "default"

  -
    scope:
      path: "Fallout3"
      type: "pages"
    values:
      layout: "default"
  -
    scope:
      path: "Fallout4"
      type: "pages"
    values:
      layout: "default"

Then I add that and it passes travis but still the above URL doesn’t work.

Then I went to the templates page and looked in the links section.

It says that possibly my pages are in /pages/folder/filename.md.

<a href="/pages/Fallout3/Records.md">FO3 Records</a><br>

So I change the link to that.

https://tes5edit.github.io/pages/Fallout3/Records.md

Then when I hover over the link I see what I have above which isn’t where I put the files so it still doesn’t work.

Then I realized a step told me to add permalink data to the file so I removed it to test.

permalink: {{ site.baseurl }}/Fallout3/Records.md

I removed that beause I don’t have a baseurl set up in _config.yml. Because when I added baseurl: https://tes5edit.github.io/xEdit-Wiki/ to my _config.yml then the site no longer had the style cheet applied.

Then I tried looking for other pages using folders. I had started at the top of the list of Sites once before but I don’t really know what I’m looking for anyway. Never saw antying that might be what I am using. So since I’m documenting my trials I thought I’d start from the bottom.

Then I came across https://github.com/ganesshkumar/ganesshkumar.github.io/

Now, this site had a pages folder and in that there was a deep-learning.md file. It had permalink: /deep-learning.html at the top which is confusing because it’s an md file. I wanted to try it but, I don’t want permalinks because I need to use folder with files that have the same names, so I need it to be /folder/filename or /folder/folder/filename. Then I thought I’ll add all that but I didn’t know what it would do because I don’t want it to confuse anything if I have /Fallout3/Records.html in one file and /Fallout4/Records.html in another.

<a href="/Fallout4/Records.html">FO4 Records</a><br>
<a href="/Fallout3/Records.html">FO4 Records</a><br>

After adding permalink: /Fallout3/Records.html etc to the files it still didn’t work.

So keep going and I find https://github.com/krajit/krajit.github.io

They also have an MD file with the permaklink added of /teaching/MAT431/heatEquation.html in HeatEquation.md so then I download their source and see that they call that from sidebar_pdeSideBar.html using href="heatEquation.html", which won’t work because I have three files all named “Record.md” so I need to use the folder names.

exclude: [".gitattributes", ".gitignore"]

defaults:
  -
    scope:
      path: ""

So I add that seeing it in a few places and it doesn’t make <a href="/Fallout3/Records.html">FO3 Records</a><br> work either.

Then I find this site https://github.com/ThemeJekyll/themejekyll.github.io/blob/master/_config.yml

It uses the themes folder and collections so I have to give up on that because I’m not using that folder.

baseurl: ""
url: ""
defaults:
  - scope:
      path: "Fallout3"
      type: pages
    values:
      layout: default
  - scope:
      path: "Fallout4"
      type: pages
    values:
      layout: default
  - scope:
      path: "FalloutNV"
      type: pages
    values:
      layout: default

but I thought I add this again and then just mass copy the folder from root and put them in pages and cross my fingers.

EDIT: Also I tried other things and travis missed this typo. Notice the layout above gems.

title: xEdit-Wiki
description: xEdit Wiki and Documentation Site
google_analytics:
# show_downloads: true
theme: jekyll-theme-cayman
baseurl: ""
url: ""
defaults:
  - scope:
      path: "Fallout3"
      type: pages
    values:
      layout: default
  - scope:
      path: "Fallout4"
      type: pages
    values:
      layout: default
  - scope:
      path: "FalloutNV"
      type: pages
    values:
      layout: default
layout: themes
gems:
  - jekyll-mentions

So then I figured since this works for other people it has to work for me. So I thought I would add this.

<a href="/Fallout3/Records.html">FO3 Records htm slash</a><br>
<a href="Fallout3/Records.html">FO3 Records htm</a><br>
<a href="Fallout3/Records.md">FO3 Records md</a><br>
<a href="/Fallout3/Records.md">FO3 Records md slash</a><br>

I added that and kept all the previous changes. The link FO3 Records htm worked. I about jumped out of my chair.

So then I squashed all my commits, deleted folders, deleted things I didn’t think I knew why I added them and in the end all I needed was to add this to the Records.md files.

---
layout: default
title: xEdit-Wiki
permalink: /FalloutNV/Records.html
---

And then use this for the link

<a href="Fallout3/Records.html">FO3 Records htm</a><br>

And once I am at the list of records, those are referencing other .MD files and thankfully I don’t have to add any Front Yaml data or change the names of the files or anything. It just works.

Somehow I feel I could have done that in 1/8th the time.

Jekyll takes in MD files and as long as they have front matter converts them to html so you never link to a .md file it is an html file - that is what makes MD so cool, you don’t have to write html. But your website needs html to display the page properly. Jekyll works as a converter.

Highly recommend investing a few hours in watching some tutorials on youtube, this is an excellent series of about 40 short videos about jekyll - it is a few years old but should still be very relevant:

and I am sure there are several others for html and css. If you are new to all 3 you have some learning to do, that is for sure. I have found it to be a continuous process but has been fairly easy. Couldn’t have done it without youtube. Or at least that made it much much easier.

I watched those and thought of following along with them but the installation page for Jekyll requires make and gcc but the links are to outdated Windows NT source code that I would have to compile myself. Thanks for trying to help me. It’s pretty useless at this point. I just have to upload to GitHub over, and over, and over, and over, 12 times until I get it right. I just have to work with what available for us Windows people. I just don’t have a Mac.

I created a website that might help you to get started with Jekyll: http://jekyllcodex.org/

If you have any questions, just send me an email/tweet/message at Stack Overflow (user: JoostS).

Happy coding!