Please document how to add this template to an existing repo

[plastikfan]

Hi this is a great template and I have watched your videos, so thanks for that. However I do have an issue. You assume that the bootstrap template is going to be use on a new repo. I am not going to use it this way. I have multiple repos that I intend to write documentation for using this bootstrap template, but you don't explain how to add this to an existing repo.

It seems that jekyll can only build from a docs folder, and this can't be changed as far as I know, so I'm just gonna accept this, but to me it makes sense that it should be configurable (I would rather call this site or www). When I extract this bootstrap template in the root folder, I see these folders

• _data
• _includes
• _layouts
• _sass
• assets
• docs
• pages

So there is another docs folder. Having 2 docs folders feels wrong to me. Can this docs folder be a different name? I would hope that it could be.

So to add this to an existing folder, do we just copy everything inside this extraction root, to the repo's docs folder?

Thanks.

[evanwill]

@plastikfan bootstrap-template is a basic set up for a Jekyll site that provides the file structure, assets, and some components to quickly start a Jekyll project--the file structure itself is the Jekyll project. So yes, you are on the correct track--you need to copy the full file structure to where ever you want to set up the Jekyll project.
If you are using GitHub Pages automatic Jekyll build, then you can have it either at the root or in the docs/ folder, in any branch.

If the root of your repo is something different--for example containing some software project, and the new Jekyll project is just for creating a documentation website--the best options are to use the docs/ folder or to create a new branch which you clean out and use to host only the documentation. In these situations a lot of people also just have a separate documentation repository.

So, if you do want to build the site from the "docs/" folder, then yes, you would copy the full contents of bootstrap-template into docs/. The "docs" folder inside of bootstrap-template is just to contain information about using the template, so you could delete that or rename it to what ever you like--it is not needed for the new site.
Then you would probably want to move your existing .md files into the "pages" folder, since the template is set up to expect content there.
Then when you go to activate GitHub Pages, you choose the branch and then choose /docs option (see github pages docs).

Let me know if that makes sense!

[plastikfan]

Hi @evanwill, thanks for your response after following your instrctions and updating the _config.xml file, I am still getting strange errors. I have excluded my source code in the config inside _config.yml under the exclude key, Jekyll is getting the followng error:

 ✘ plastikfan@Janus  ~/dev/github/PoSh/Loopz λ   gh-pages ±  jekyll s
Configuration file: none
            Source: /home/plastikfan/dev/github/PoSh/Loopz
       Destination: /home/plastikfan/dev/github/PoSh/Loopz/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
     Build Warning: Layout 'page' requested in docs/404.html does not exist.
    Liquid Warning: Liquid syntax error (line 300): Expected end_of_string but found id in "{{ Fill Functee Description }}" in Elizium.Loopz/docs/Invoke-ForeachFsItem.md
    Liquid Warning: Liquid syntax error (line 242): Expected end_of_string but found id in "{{ Fill CopyFiles Description }}" in Elizium.Loopz/docs/Invoke-MirrorDirectoryTree.md
  Conversion error: Jekyll::Converters::Scss encountered an error while converting 'docs/assets/css/custom.scss':
                    Error: File to import not found or unreadable: theme-colors. on line 28:1 of custom.scss >> @import ^ 
                    ------------------------------------------------
      Jekyll 4.2.0   Please append `--trace` to the `serve` command 
                     for any additional information or backtrace. 
                    ------------------------------------------------

This looks like Jekyll is still processing files that have been excluded. My repo is a powershell module and powershell modules user there own docs folder which contains .md files. It looks like Jekyll is processing those md files which it shouldnt be becasue they have excluded by this line in _config.yml:

exclude: [docs/, Rakefile, README.md, LICENSE, azure-pipelines.yml, Elizium.Loopz/, VERSION]

The 'Elizium.Loopz/' entry here is the root of the powershell module and it has a docs folder that I just mentioned. This should not be being processed.

I think I may have to use a separate repo for documenting my source code, but I would rather not.

There is also a strange sass error:

plastikfan@Janus  ~/dev/github/PoSh/Loopz λ   gh-pages ±  jekyll s --trace
Configuration file: none
            Source: /home/plastikfan/dev/github/PoSh/Loopz
       Destination: /home/plastikfan/dev/github/PoSh/Loopz/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
     Build Warning: Layout 'page' requested in docs/404.html does not exist.
  Conversion error: Jekyll::Converters::Scss encountered an error while converting 'docs/assets/css/custom.scss':
                    Error: File to import not found or unreadable: theme-colors. on line 28:1 of custom.scss >> @import ^ 
Traceback (most recent call last):
        29: from /usr/local/bin/jekyll:23:in `<main>'

in the custom.css file:

@import
  "theme-colors", "template", "custom"
;

I don't know why theme-colors is not available, it exists as theme-colors.csv in the docs folder. (See this is why I don't like the idea of have a docs/docs folder, because that just leads to more confusion)

[plastikfan]

I wonder if line endings has anything to do with this. I am using wsl2 on ubuntu. I extracted the bootstrap zip inside ubuntu using the unzip command. In visual studio code, the lin ending indicator for the custom.scss file indicates LF (as oppose to CRLF).

[evanwill]

@plastikfan if your Jekyll project is in the docs/ folder, then you need to start Jekyll jekyll s from inside that folder, not from the root. Your build message above says Configuration file: none, meaning it is not reading the _config.yml--it expects to find it in the place where you are running jekyll s. If it isn't reading the _config.yml, then it isn't getting your exclude or anything else.

Line endings don't matter to VS code or wsl2. PowerShell might care.

[plastikfan]

Hi @evanwill,

thanks for that. I restarted jekyll from the docs folder and that worked. However, when I now visit the site, none of the bootstrap styling is being applied so the page looks like this:

I looked in the index.html in the generated _site files and I couldnt see anything obviously wrong in there, but there is probably an incorrect path reference somewhere, similar to the way I accidently ran Jeykll from th wrong directory. So would you have any idea why bootstrap styling isnt being applied?

Thank you.

PS: I realised that I can't really have my site in a separate repo from my source code, because the url would also have to be different, which is just another headache I'd rather not have.

[evanwill]

@plastikfan not really sure? I just pulled down your https://github.com/EliziumNet/Loopz , looked at gh-pages branch, cd docs, jekyll s, and the template part seems to be working fine for me.

In that version of the code there isn't a url or baseurlset, but in your image above the url is http://127.0.0.1:4000/Loopz/about.html, so I assume you are trying to set a baseurl? If that value isn't structured correctly is the most likely way to scramble the urls to the assets.

For example if this is the repo, https://github.com/EliziumNet/Loopz
The _config.yml options would look like:

##########
# URL VARIABLES [optional!]
#
# Optional if using GitHub Pages! If building manually, these must be set correctly.
#
# use url for the domain, e.g. https://thecdil.github.io
# on gh-pages follow the pattern: https://username.github.io
url: https://EliziumNet.github.io
# use baseurl to add subsection of the domain, e.g. /timelinejs-template
# on gh-pages this is a / followed by the name of the repository
# baseurl is your github repository's name prefixed with a /
baseurl: /Loopz
# location of code, the full url to your github repository
source-code: https://github.com/EliziumNet/Loopz

Keep in mind that jekyll s generates absolute urls in the code starting with http://127.0.0.1:4000/, so if you just double click the file it won't be able to find the assets unless jekyll s is running. When you jekyll build those will be replaced with your real url value (on github pages, if url is left blank, it is automatically filled in with the correct url).

[plastikfan]

I havent commited my curent version yet. My local version has an updated version of the _config.yml with those fields setup:

#######
# SITE SETTINGS
#
title: Elizium.Loopz PowerShell module documentation
description: "Documentation for Elizium.Loopz PowerShell module"
year: 2021
author: plastikfan
# add search box to navbar, true/false
search: true

##########
# URL VARIABLES [optional!]
#
# Optional if using GitHub Pages! If building manually, these must be set correctly.
#
# use url for the domain, e.g. https://thecdil.github.io
# on gh-pages follow the pattern: https://username.github.io
url: https://eliziumnet.github.io
# use baseurl to add subsection of the domain, e.g. /timelinejs-template
# on gh-pages this is a / followed by the name of the repository
# baseurl is your github repository's name prefixed with a /
baseurl: /Loopz
# location of code, the full url to your github repository
source-code: https://github.com/EliziumNet/Loopz


#######
# BUILD SETTINGS [usually leave as is]
#
# Defaults to simplify front matter,
# all files in the "pages" folder will be output at root of site
defaults:
  - scope:
      path: "pages"
    values:
      layout: page
      permalink: /:basename:output_ext

# ignore stuff
exclude: [docs/, Rakefile, README.md, LICENSE, azure-pipelines.yml, Elizium.Loopz/, VERSION]

[plastikfan]

I'm thinking that I should do the initial setup using the github ui because I managed to get this working on a test repo I have (https://plastikfan.github.io/FakeBuddy/). The problem with my Loopz repo is that I tried to do the initial setup locally using jekyll server and so far my local version is not quite working yet, because of the missing bootsrap styling. (That FakeBuddy repo works even though the config file wasnt even updated).

[plastikfan]

Ok. so I just commited my changes then pushed. I went to test it locally again and it started to work. I have no idea what happened here. My local changes were only un-commited when it wasnt working, then I commited, then it started working. Confused!

[plastikfan]

Thanks for helping me out with this @evanwill

[plastikfan]

Perhaps I shouldn't close this if you intend to make some additions to your documentation to indicate how to add this template to an existing repo. Could I also suggest you have a troubleshooting section that documents anticipated mistakes users might make, eg starting the jekyll server from the wrong directory! (Feel free to close if you want tho)

[evanwill]

Glad you figured it out @plastikfan . the process is helpful for thinking about teaching and doc-ing.

Not sure what was going on in your last mystery--only guess would be browser caching confusing things--when developing its a good idea to use a private window with dev tools open, then you can hold down refresh to get options to hard refresh everything.

Good luck with the project!

[plastikfan]

Ok great thanks. And thanks to you for creating this useful template.
Cheers

[plastikfan]

PS: that styling issue with bootstrap can be fixed in the local version of jekyll by running 'jekyll clean', then rerunning build/serve