I use github actions as it is pretty powerful and simple.

Important: If you use enterprise github you need a self-hosted runner which needs to be installed on a VM github.com does not need this

Initialize a new repository

First, create a new repository called infrastructure.

I created it as a public repository so anyone can clone it and deploy my infrastructure to play around with it.

clone repository

Now clone the folder to your local computer.

Go to Code, then copy the link. Now go to your GitHub Desktop and Add the repository to the root folder - 001328 in my case.

set up credentials

The next step is to set up the azure credentials we will need to deploy anything into our azure subscription. We do this via GitHub Secrets.

Secrets are environment variables that are encrypted. Anyone with collaborator access to this repository can use these secrets for Actions. Secrets are not passed to workflows that are triggered by a pull request from a fork. Learn more.

Let’s start with adding three secrets.

• subscriptionid
• azurelogincreds
• resourcegroupname

All secrets we use for now are repository secrets. Later on we will add multiple environments and change the secrets to reflect these changes.

To start, go to the Tab Settings and then you will find Secrets in the Navigation pane on the left. Here, select Actions.

subscriptionid

First we will start with a subscriptionid.

Open the azure portal and search for subscriptions in the search bar on top.

From here either select the subscription you want to use or create a new one if it is empty. Copy the Subscription ID, it should have this format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Switch back to the github tab and add a new repository secret via the button.

Then add the Subscription ID as the VAlue and give it a name you like.

I always use lowercaps without hyphens, underscores or other funky stuff as different tools sometimes don’t like it and this way I can keep it consistent! Also no numbers at the beginning or end Here it doesn’t matter as GitHub transforms your secret in UPPERCAPS anyways

And you are done!

Please note that nobody can see this secret again so make sure to save it in your password safe of choice

You can only update the secret, if you do then you have to re-enter it and save again!

azurelogincreds

The next secret we add are azurelogincreds.

These are the azure login credentials GitHub uses login to azure and create resources. To do this it uses a Service Principal which we will create before.

The azure login credentials have this format:

{ “clientId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”, “clientSecret”: “xxxxxxxxxxxx”, “subscriptionId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”, “tenantId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” }

We already have the subscriptionId and you can find the tenantId by searching for tenant properties in the azure search bar (just like you did for the Subscription ID).

In the properties you can copy the Tenant ID by selecting the little Icon next to the ID.

Next step: Get a clientId and the clientSecret. This is a Service Principal.

Service Principal setup

• Search for App registrations

• select New registration

• give it a good name and select Register

• select Certificates & secrets on the left blade, then select New client secret

• choose a good name, an expiration date (good habits for security) and add the secret

• save the value in a secure location (like Keepass - yes, notepad++ - no). You can only see the value one time.

• go to the Overview and you can copy the client ID

Now we have everything we need to complete the azure login credentials! Here is an example how it should look like (subscriptionId and tenantId are randomized):

{
"clientId": "f19302cf-18f1-4789-85fa-048a7f03471e",
"clientSecret": "fdr8Q~Z60kVE3zjGfOCl3EMtmy~ZCx2dL5pLic~k",
"subscriptionId": "64dbf7h2x-5oi4-4ap8-d7r2-de5489b4j8pq",
"tenantId": "73xz6g8q-6uu2-1tt2-j6i8-po7823l5j5qs"
}

In case you work for a bigger Enterprise you will see an Access denied. Then you need to set up the service principal through an alternative route, please talk to your network team to do so. The company I work for has a separate tool to create anything in the Active Directory and I need a dedicated admin user to create a client secret.

• Go back to the Settings in your GitHub Repository and select New repository secret

Whatever you will deploy now will be deployed to the Tenant and Subscription you entered. For multiple Environments I recommend to have one secret each.

• azurelogincreds_dev
• azurelogincreds_test
• azurelogincreds_prod

I need to give permissions to the service principal I suppose

Done with the preparation!

Next step: Deploy a resource group

Secret: resourcegroupname

First, add another secret for the name of your resource group

• Select New repository secret within Settings/Secrets/Actions
• Enter the name you want to give your resource group and select Add secret

Note: I recommend to follow the recommended abbreviations for Azure resource types I use lowercaps without hyphens as some resources don’t allow it and append the abbreviation as a suffix

Folder structure

Create 2 Folders in your repository: .github and templates. Within .github, create another folder workflows. Push all changes to GitHub.

• The Folder .github will contain the yaml files which trigger the actual deployments.
• The Folder templates will the resource templates.

resource group template

Create a custom template for the resource group deployment by creating a new file in your preferred editor, like visual studio code. Enter the following code and save as resourcegroup.json in the folder templates.

Note: I recommend to use the location closest to you. For me it is eastus2. The guys from azuretracks have put together a nice list with all the abbreviations. Here is another list.

{
    "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters":
    {
        "ResourceGroupName": { "type": "string" }
    },
    "resources": [
        {
            "type": "Microsoft.Resources/resourceGroups",
            "apiVersion": "[providers('Microsoft.Resources','resourceGroups').apiVersions[0]]",
            "name": "[parameters('ResourceGroupName')]",
            "location": "eastus2"
        }
    ]
}

resource group workflow

Create a new file and paste the following code and save as resourcegroup.yaml

Note: the region is the location of the deployment within azure! If you change it after you already deployed the template, you will get an error in the template validation. If so, you need to remove the deployment via the azure shell $deployments = Get-AzManagementGroupDeployment -ManagementGroupId ES foreach ($deployment in $deployments) {Remove-AzManagementGroupDeployment -ManagementGroupId ES -Name $deployment.DeploymentName}

name: Resource Group Deployment
on: workflow_dispatch
jobs:
 build:
  runs-on: ubuntu-latest
  steps:
   - uses: actions/checkout@v2

   - name: Login to Azure
     uses: azure/login@v1.1
     with:
       creds: $

   - name: Create Resource Group
     uses: azure/arm-deploy@v1
     with:
       scope: subscription
       subscriptionId: $
       region: eastus2
       template: ./templates/resourcegroupdeployment.json
       parameters:
         ResourceGroupName=$

run the workflow

• push everything to GitHub

• In GitHub, go to the tab Actions and Select the workflow Resource Group Deployment

• Select Run workflow

• If you select the name of the workflow you can watch the build

• Once you see a green button you are done and can test if you see your new resource group!

My biggest changes are the introduction of a secondary color instead of the grey and I want to do something with the tags

What you need to know is you have _layout and _base for your general styling and you have the minima.scss for your variables which are depicted by $

Now it’s time to think about your color scheme. you need a main color and a secondary color - for me the main color should be dark and the secondary color should be light

Basic adjustments

For the basic adjustments I want to get a primary and secondary color scheme. Then I want to adjust the current template a little bit so my colors are reflected.

_minima.scss

First we go into _sass/minima.scss. Here, we add a secondary-color variable - play around what color you like. You cam also changed the brand-color here.

simple is key here and we want to focus on content, a small resemblence to your company leads a long way - this should still be an enterprise-ready wiki

_layout.scss

Now we can adjust the _layout.scss. We only really add one thing for post-tag and then adjust the rest a little.

Also adjust the header sizes here.

You will see that the Header sizes are not yet consistent. You can adjust this within .post-content

.post-content {
  margin-bottom: $spacing-unit;

  h1 {
    @include relative-font-size(2);

    @include media-query($on-laptop) {
      @include relative-font-size(1.75);
    }
  }

  h2 {
    @include relative-font-size(1.75);

    @include media-query($on-laptop) {
      @include relative-font-size(1.75);
    }
  }

  h3 {
    @include relative-font-size(1.5);

    @include media-query($on-laptop) {
      @include relative-font-size(1.375);
    }
  }

  h4 {
    @include relative-font-size(1.25);

    @include media-query($on-laptop) {
      @include relative-font-size(1.125);
    }
  }
}

Tags

I kinda like what this guy did.

Create a new class “post-tag” - funny enough is that all the tags already have the class attached to it so we can just use it as a base. add this code to your Custom segment in your _layout.scss

.post-tag {
  color: $brand-color;
  display: inline-block;
  background: $secondary-color;
  padding: 0 .5rem;
  margin-right: .3rem;
  margin-bottom: .1rem;
  border-radius: 4px;
  &:hover {
    text-decoration: none;
    background: $brand-color;
    color: $secondary-color;
  }
}

Site Header

Change the colors on border-top and border-bottom and remove the &:visited.

/**
 * Site header
 */
.site-header {
  border-top: 5px solid $brand-color;
  border-bottom: 1px solid $secondary-color;
  min-height: $spacing-unit * 1.865;

  // Positioning context for the mobile navigation icon
  position: relative;
}

.site-title {
  @include relative-font-size(1.625);
  font-weight: 300;
  line-height: $base-line-height * $base-font-size * 2.25;
  letter-spacing: -1px;
  margin-bottom: 0;
  float: left;

}

Then I changed the color of the page links to the other pages

  .page-link {
    color: $brand-color;
    line-height: $base-line-height;

    // Gaps between nav items, but not on the last one
    &:not(:last-child) {
      margin-right: 20px;
    }
  }

I also changed the menu icon (is showed if you narrow your screen)

    .menu-icon {
      display: block;
      float: right;
      width: 36px;
      height: 26px;
      line-height: 0;
      padding-top: 10px;
      text-align: center;

      > svg {
        fill: $brand-color;
      }
    }

Site footer

Change the color of the border to your secondary color and adjust the wrapper of your footer

/**
 * Site footer
 */
.site-footer {
  border-top: 1px solid $secondary-color;
  padding: $spacing-unit 0;
}

.footer-col-wrapper {
  @include relative-font-size(0.9375);
  color: $brand-color;
  margin-left: -$spacing-unit / 2;
  @extend %clearfix;
}

Page content

Here we just adjust the meta information for each post.

Note: Depending on you secondary color you need to make it darker or lighter so it is good to read.

.post-meta {
  font-size: $small-font-size;
  color: darken($secondary-color, 30%);
}

_base.scss

We can adjust the images, links and icons in _sass/minima/_base.scss

Images

For images I want to add a shadow to make them pop a little.

/**
 * Images
 */
img {
  max-width: 100%;
  vertical-align: middle;
  box-shadow: 5px 8px 8px #5e5e5e;
}

If you want to change the shadow to a “glowy” style you can als try this.

box-shadow: 0px 0px 11px #000000;

Links

For the links I just removed the visited because I always find it irritating when websites have different colors for links. Other changes are colors and the underline for the social media links

/**
 * Links
 */
a {
  color: $brand-color;
  text-decoration: none;

  &:visited {
    color: $brand-color;
  }

  &:hover {
    color: lighten($brand-color, 15%);
    text-decoration: underline;
  }

  .social-media-list &:hover {
    text-decoration: none;

  }
}

Icons

change the icon fill to your brand color

/**
 * Icons
 */

.svg-icon {
    width: 16px;
    height: 16px;
    display: inline-block;
    fill: #{$brand-color};
    padding-right: 5px;
    vertical-align: text-top;

    &:hover {
      fill: #{lighten($brand-color, 20%)};
    }
}

DONE

One way to do this is to simply add additional pages, then add a navigation menu and hardcode everything. While this probably works I just hate hard-coded stuff and don’t think anyone should waste time and effort with keeping code alive if there is not a really good reason to do so.

Lucky for us Jekyll offers another way to do navigation with its “built-in plugin” called jekyll-archives. Unlucky for us GitHub pages does not support jekyll-archives..

But this guy here (Big time Kudos!) found a pretty cool solution which I used as a base and customized a little bit..(due to my complete lack of html skills it took me a couple of days but if I can do it, you can too!)

Actually, I had to invest quite some work because I didn’t just want a list with all posts, but I wanted my list to actually filter when I click a tag!

Important note: Jekyll is static and gets executed when the page is loaded. To get the interaction we need to add some Javascript and filter out the posts we don’t want to see upon a click.

Solution

Most of the changes will be in your home.html

Go to your folder _layouts and open your home.html. This is what we will change first - if you want you can copy it for your references so you can always go back (without going through your version control).

Step 1: create a list of tags

First you add the following code at the top of the home.html to extract all the tags, sort them and remove duplicated ones.

{% assign rawtags = "" %}
{% for post in site.posts %}
	{% assign ttags = post.tags | join:'|' | append:'|' %}
	{% assign rawtags = rawtags | append:ttags %}
{% endfor %}
{% assign rawtags = rawtags | split:'|' | sort %}

{% assign tags = "" %}
{% for tag in rawtags %}
	{% if tag != "" %}
		{% if tags == "" %}
			{% assign tags = tag | split:'|' %}
		{% endif %}
		{% unless tags contains tag %}
			{% assign tags = tags | join:'|' | append:'|' | append:tag | split:'|' %}
		{% endunless %}
	{% endif %}
{% endfor %}

Step 2: add the tags to the site

Then add the list of tags as an element above the post-list header element in line 32. This code adds each tag as a hyperlink and executes the function click_the_tag with the id of the tag that we clicked.

{% for tag in tags %}    
<a id={{tag}} class="post-tag" href="#{{ tag | slugify }}" onclick="click_the_tag(this.id)"> #{{ tag }} </a>
{% endfor %}

I also added a tag #all at the beginning of the tag list to show all posts again. To do this we can simply add the following code above

<a class="post-tag" href="">#all</a>

Step 3: create the base function

Now we are ready to add the frame of our javascript function. The frame will just select the clicked tag and change the element named tagID to this tag.

<script>

  function click_the_tag(clicked_id) {
    document.getElementById("tagID").innerHTML = "#" + clicked_id;
  }

</script>

To immediately test the function we also adjust the html a little.

<h2 class="post-list-heading">{{ page.list_title | default: "Posts" }}</h2>

Replace the code above with the code below.

<h2 class="post-list-heading"><span id="tagID">#all</span> posts</h2>

It should look like this now:

Test it and see how it changes based on what you click. Your url changes too, so you can easily see what was clicked.

Step 4: add the logic to the function

Now you can add the rest of the function. First we create an object that stores all posts with the class “post-elements”, then it iterates through them and adds a class “hidden”. Then we do the same for the posts with the class that we selected, iterate through them and remove the class “hidden” again.

const allPosts = document.getElementsByClassName("post-elements");
for (const post of allPosts) {
	post.classList.add("hidden");
};
const selectedPosts = document.getElementsByClassName(clicked_id);
for (const post of selectedPosts) {
	post.classList.remove("hidden");
};

remember: the whole page is rendered already so we actually just need to hide some unwanted elements

Step 5: add a class to your CSS

Now we go to your folder _sass/minima and add a class named hidden to the file _layout.html.

Add a new segment at the top for Custom.

/**
 * Custom
 */

.hidden { display: none; }

Step 6: add the new class to your elements

Now we add the class post-elements to each element that links to a post in home.html. We also add a class for each tag a post has with the same name. This will then be used by the function to identify where to remove the class “hidden”.

      {% assign joinedtags = post.tags | join:" " %}
      <li class="post-elements {{ joinedtags }}">

Test it and see how the list changes..

Step 7: add the tags to each post in the list

Last thing is to add the tags meta information to each post link in the list. Just add the following span element which sorts, joins and adds each tag for the respective post.

<span class="post-meta"> {{post.tags | sort | join:" #" | prepend: "| #"}}</span>

Step 8: add the tags to each post site

Last step is to also add the information above in every post. Go to _layouts/post.html and insert the following code at the end of the p-element with the class post-meta.

Note how we use page.tags now instead of post.tags

<span>{{page.tags | sort | join:" #" | prepend: "| #"}}</span>

Also, I changed the first part of th author-element to get rid of the bullet point.

| <span itemprop="author" itemscope itemtype="http://schema.org/Person"><span class="p-author h-card" itemprop="name">{{ page.author }}</span></span>

References

Here I learned how to get the ID from a clicked tag so you can filter down the posts.

The display property stuff comes form here

More References for Jekyll archives

This guy shows a way to deploy the archives plugin on GitHub pages. This could actually work but I think it is way to much effort and a lot harder to implement than my solution.

You can check out how to work with Jekyll archives in general here and here if you want to deploy it to your own webserver.

We will cover these things here:

1. how to create additional pages
2. how to create posts
3. markdown basics

Pages

You can add more pages to the navigation on top by add more markdown files in the folder _pages. Every page just needs these elements at the beginning of they page.

---
layout: page
title: About
permalink: /about/
---

If you want to adjust the layout, just go to _layouts, create the layout (html) you like and you can use it at the beginning of the page. The title adjusts the Header on the page and the link. The permalink is the actual link you can use for navigation.

To not overload the page I just added 2 more pages, about and credits

Posts

To add a post you can just create a new markdown file in the folder _posts. Please follow this naming convention: yyyy-mm-dd-enter-your-text

Reason is that jekyll automatically creates a URL structure and will not detect any files not in this format. Posts that are not ready to publish yet can be put into the folder _drafts. This provides better organization and also gives you the option to test your result by running jekyll locally with this option:

bundle exec jekyll serve --drafts

Each post has a header, layout is post, title is whatever you want to see, the date sorts your posts and categories structures your URL and provides Filter capabilities. Categories is one of two standard features the vanilla jekyll framework minima provides. The other one is Tags which I personally find a little more intuitive and will use for adding navigation to my page (see next posts).

---
layout: post
title:  "Creating content"
date:   2022-07-28 01:10:00 -0400
categories: jekyll update
tags: github-pages
---

Markdown basics

Images

You can add an image by saving it in the folder assets/images, then adding this line of code to your post or page.

![picture](/assets/images/picture.png)

Links

You can add a Link by adding this line:

[Random Link](https://jekyllrb.com/)

Codeblocks

You can add a codeblock with the highlight command. This website here provides all supported languages

{% highlight liquid%}

{% endhighlight%}

Markdown Resources

As this is not a Blog about markdown I will stop right here, there are a ton of better resources out in the web. The best website for markdown in my opinion is markdownguide and of course jekyllrb!

Highlighting

Minima theme preview

This post will cover these topics:

• add readme and license
• add a favicon
• change the Title & Description
• change the Footer
• change the permalink

Add readme and License

If you want to run this as an open source project, now is the time to add readme and a license (obviously not required for enterprisev usage)

We didn’t do this initially to ensure we have a completely empty repository that we can first populate with our new website

The easiest way to do this is to create a new file and save it as README with the markdown extension. Once you push it to GitHub its content will be displayed below your files. You can populate it just like any other post or page with markdown.

Then create another file and save it as LICENSE without any extension

Now push everything to GitHub and open it there to edit (the little pencil on the bottom right).

this give you the option to choose a standard license template:

I chose the MIT License and commit at the bottom, create a pull request and then delete the branch add-license-1 and the file LICENSE.txt

Check if there is still the other LICENSE.txt file in the repository. If so you can delete it

Great Job!

This is how it should look like now

Add a favicon

adding a favicon is a fun thing to do

a favicon is the “favorite icon” you can see on top of a website

One way to do a quick favicon is to use powerpoint and Quickly draw something.

Now you can put this image into the favicon generator

after it is generated the favicon generator give you everything you need to put it in your head.html just download the package and place it in a folder “favicon” under “assets”

Next go to the folder _includes and create a new file custom-head.html

here, paste the code from the favicon generator

<link rel="apple-touch-icon" sizes="180x180" href="/assets/favicons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/assets/favicons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/assets/favicons/favicon-16x16.png">
<link rel="manifest" href="/assets/favicons/site.webmanifest">
<link rel="mask-icon" href="/assets/favicons/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/assets/favicons/favicon.ico">
<meta name="msapplication-TileColor" content="#ffc40d">
<meta name="msapplication-config" content="/assets/favicons/browserconfig.xml">
<meta name="theme-color" content="#ffffff">

After you saved it go to _layouts/default.html and add the following code

%- include custom-head.html -%

After you pushed it to github you can enter your domain into the favicon checker

Change the Title & Description

You can change the title and description of your website in the _config file.

and that’s already it.

Change the Footer

Now let’s see if we can make the Footer how we want it.

In my opinion all that Design stuff should be done by designers, I just want to make fast and simple adjustments so I have something I am happy with.

That means for me:

• remove my personal email
• remove twitter and add linkedin an rss

all you need to do is to go into the _config file and do these steps:

• remove the email
• remove twitter_username
• add linkedin_username: youruser
• add rss: subscribe

last step is to remove the texztx “subscribe via RSS” from the main page. go to home.html and remove line 31

Change the permalink

I don’t want the URL structure to include the date but I like it a little simpler.

To adjust the URL go to your _conf file and add this line

permalink: /blog/:title/

Steps:

• understand the current theme
• adjust
• build a clean “vanilla” folder structure

Understand our theme

To really make this website yours we will move the folder structure of your theme into your working folder. This way you have a great (secure!!!) base and we can start customizing.

• First, we will look at the current structure

To do so, please open command prompt and go to the directory of your wiki

cd xxx/GitHub/001328/wiki

From here, ensure the jekyll bundler is installed

gem install jekyll bundler

then execute the following code, it will point you to the path where the jekyll theme you are using is installed (for me it is here: C:\Ruby31-x64\lib\ruby\gems\3.1.0\gems\minima-2.5.1)

bundle info minima

jekyll has a very neat feature: if you want you can have adjust a template with new folders etc and it will first look into your main folder. If it doesn’t find sth it needs it will then look into the theme folder.

You will see something like this:

To understand the process and to fully customize, we can just copy the folders into your github folder. Do not copy the License or the readme, we will add this later

this is how your folder should look like now:

what did we just copy?

• _includes - here the fine-grained html-files are included that are used by the layouts
• _layouts - container for the base layouts, post.html for example is the layout for any posts. it uses the default.html file as a base. default again uses head.html, header.html and footer.html
• _sass - this is the container for all the sass files (make it pretty)
• assets - here everything is stored that the website needs - images for example

the great thing is that you can now quickly screen every file for anything you don’t like from an enterprise perspective I am always worried I miss something that I don’t want in an internal wiki, often “free” templates have ads for example and I would rather not have one in an internal wiki.. ;)

next step: add some organization with a few more folders

image folder

Next I want to add an image folder as it makes sense to me that images should be organized somewhat

drafts folder

add a folder _drafts to store blog entries that are not ready to publish yet. the great feature of jekyll here is that you can run and test your website locally that takes this folder into account so you can see it how it would look like

bundle exec jekyll serve --drafts

pages folder

let’s also add a folder _pages to store the html pages we want to build.

Currently there are two separate pages, index and about. The index page always needs to be at the root folder so please do not move it personal opinion incoming: it seems to be best practice though to move the about page and all other pages you maybe want to add to the _pages folder

last step is to go into the config file and add

include:
  - _pages

GREAT! now we have a pretty solid and sustainable folder structure! Before doing anyting else, please run bundle exec jekyll serve to check if everything still works

Examples

you can find an example folder structure here

These are other great themes that can give you some inspiration and folder structure:

minimal-mistakes/ github

beautifuljekyll/ github

The product I am building is called the azure data platform, so I want to use azuredataplatform.net

Steps:

1. Find a great domain and buy it
2. Point the domain to GitHub
3. add the domain to GitHub

Step 1: Find a great domain and buy it

There are tons of locations where you can buy a domain. One of the biggest is GoDaddy, I prefer Google Domains because their prices appear to be more stable to me.

Once you bought it it will appear under My domains and you can go to the properties with the Manage Button

I will use my own site azuredataplatform.net

Step 2: Point the domain to GitHub

In the Manage Settings you will find DNS

From here we need to point the new domain to GitHub To do so, please add 2 custom records: 1. Type A record 1. Type CNAME record

The Type a record needs to point to GitHubs IP-Addresses. Do not put anything in the field “Host name”. Enter the following records into the field “Data” (add more with the +)

• 185.199.108.153
• 185.199.109.153
• 185.199.110.153
• 185.199.111.153

The Type CNAME record needs to point to your GitHub repository. Please create a new record and enter www in the field “Host name”. Enter the following record into the field “Data”.

• 001328.github.io

Then hit Save

Step 3: add the domain to GitHub

Now go to your github repository, open the settings for Pages and enter your newly created domain into the field for Custom domain and Save

It will check the DNS records you just made and once successful publish your new website.

Once the DNS check is successful your website is published with your new name! Please be aware that GitHub needs to provision a TLS certificate to ensure it’s secure.

Once the certificate is provisioned, select the option Enforce HTTPS

Attention: It can take an hour until your website works properly

Step 4: Fix CSS

When you change your domain name your website will probably look like this

To fix it just adjust the baseurl and url in your local config file, then push the changes to github

remember to wait 1 Minute so the CSS can load

The final result:

The End

This Tutorial follows the offical Github Docs with a littlle help from this guy

By the way - DNS means Domain Name Service

• zero trust (I don’t know what others put into it) - but if you follow these steps you can build your own, perfect template
• version updates
• readability - a vanilla template is easy to scan
• customizing - if I customize a vanilla template everyone can participate easily

Steps:

1. Create new repository
2. Install Jekyll
3. Run Jekyll locally with Vanilla template
4. Publish to GitHub

Step 1: GitHub Repository

• Go to github and create a new Repository

  I created a dedicated organization (001328) for it as I want all repositories of my azure data platform grouped together and I have it public so it’s free. If you do this for a company either make it private or use github enterprise

• clone the new repository (wiki) to your local computer, use any local path you like

  • (link - top set up a github account / organisation)
  • (link - how to set up github on your local computer)

• you will find the url in your github repo

• open github desktop and clone your new repository to your computer via the Add Button

• enter the URL you copied from github.com

• once cloned you have an empty folder on your local machine

Step 2: Install Jekyll

Following the quickstart instructions on jekyllrb provides you a great starting website with the very simpel minima template. To host it for free we will change only one step.

• installation for windows (you can find other guides here)
  1. Download and install Ruby+Devkit with default options.
  2. Run the ridk install step and choose the options MSYS2 and MINGW development tool chain

     open command prompt and check for proper installation with ruby -v

Step 3: run your website locally

1. open command prompt and go to the cloned directory cd xxx/GitHub/001328 do not cd into the folder yet

2. Open command prompt window (start+cmd), install via gem install jekyll bundler

   open command prompt and check for proper installation with jekyll -v

3. create a new jekyll site into the newly created repository folder jekyll new wiki
4. change into your new directory cd wiki
5. Build the site and make it available on a local server bundle exec jekyll serve

   use bundle exec jekyll serve --livereload so it reflects changes

6. Browse to http://localhost:4000

in July 2023 there was the webrick gem missing - add it via bundle add gem webrick

Step 4: publish to github-pages

1. open the gemfile in the new directory (right click and open with visual studio code or notepad++)
   • comment line 10 (put a # in front), uncomment line 15 (gem “github-pages”)
2. open the config file in the new directory (add new lines and comment out the other ones)
   • baseurl: “/wiki”
   • url: “https://001328/github.io”

Note: If you want to publish your website to enterprise github you need to put the enterprise github address into url and your organization/repo in baseurl

baseurl: "/organization/repository/"
url: "https://pages.git.xxx.com"

1. publish to github in repo (commit and push to main branch)

you will now see a folder _posts and some files

1. make a github page out of it
   • go to the settings within your repository
   • open the menu “Pages”
   • enable GitHub pages with the main branch
   • check it out here: https://001328.github.io/wiki/ n(make this your address)
2. wait 1 minute so the css can load within github pages

Attention: if you want to run it local, you need to adjust the config file again so baseurl and url are empty (Step 2)

Next Steps

Now we can create our own domain and give it a custom name!

Other

minima

Minima is a one-size-fits-all Jekyll theme for writers. It’s Jekyll’s default (and first) theme. It’s what you get when you run jekyll new.

Theme preview

We will take this as the base for the section of creating-content