Add steps through creating the GitLab CI YML

.gitlab-ci.yml

@@ -0,0 +1,21 @@
+stages:
+    - deploy
+
+pages:
+  stage: deploy
+  image: rust:latest
+  variables:
+    CARGO_HOME: $CI_PROJECT_DIR/cargo
+  before_script:
+    - export PATH="$PATH:$CARGO_HOME/bin"
+    - mdbook --version || cargo install --debug mdbook
+  script:
+        - mdbook build -d public
+  only:
+      - master 
+  artifacts:
+      paths:
+          - public
+  cache:
+    paths:
+    - $CARGO_HOME/bin

book.toml

@@ -4,3 +4,8 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Creating and Hosting a mdBook on GitLab"
+
+[output.html]
+git-repository-url = "https://gitlab.com/strivinglife/book-gitlab-mdbook"
+edit-url-template = "https://gitlab.com/strivinglife/book-gitlab-mdbook/-/edit/main/{path}"
+git-repository-icon = "fa-gitlab"

src/SUMMARY.md

@@ -1,3 +1,10 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
+- [Introduction](./intro.md)
+- [Step 0: Dependencies](./step_0.md)
+- [Step 1: Getting started](./step_1.md)
+- [Step 2: Adding content](./step_2.md)
+- [Step 3: Editing content](./step_3.md)
+- [Step 4: GitLab repository](./step_4.md)
+- [Step 5: Book TOML](./tweaks/toml.md)
+- [Step 6: gitlab-ci](./step_6.md)

src/chapter_1.md

@@ -1 +0,0 @@
-# Chapter 1

src/intro.md

@@ -0,0 +1,2 @@
+# Introduction
+This book will cover how to create and host a new mdBook on GitLab.

src/step_0.md

@@ -0,0 +1,4 @@
+# Step 0: Dependencies
+If you want to use the mdBook utility to create and develop books locally you can find installation instructions on the official GitHub code repository.
+
+- [mdBook on GitHub](https://github.com/rust-lang/mdBook)

src/step_1.md

@@ -0,0 +1,36 @@
+# Step 1: Getting started
+This will assume that you have mdBook installed, but you can easily create and edit a mdBook without the CLI.
+
+These commands have been run in PowerShell on Windows, but will be similar on other environments.
+
+## Create a new book
+Create a new book by running one of the following commands:
+```powershell
+# Create a new book in the current directory.
+.\mdbook.exe init
+# Create a book in the specified directory.
+.\mdbook.exe init book-gitlab-mdbook
+```
+
+You'll be prompted on whether you want to create a .gitignore file - `y` - and the title of your book.
+
+`cd` into the new book directory, if you created one, and start up Visual Studio Code (`code .`) or the editor of your choice.
+
+We can also start the book by running the `serve` command.
+
+```powershell
+..\mdbook.exe serve -o
+.\mdbook.exe serve -o .\book-gitlab-mdbook\
+```
+
+This book will have the title we supplied, a single chapter (Chapter 1), and functionality to change the theme, search, and view and print-friendly version of the entire book.
+
+## Add Git
+Since we're going to have GitLab host the book for us we'll need to add Git. From the new book's root directory (`book-gitlab-mdbook` for example):
+
+```bash
+git init
+git add .
+# Whatever message you want to use.
+git commit -m "Initialize mdBook"
+```

src/step_2.md

@@ -0,0 +1,20 @@
+# Step 2: Adding content
+If you have mdBook up and running, you can add new content (pages) by editing the SUMMARY.md file.
+
+This summary acts as the table of contents, and if you include a link to a file that doesn't exist it will automatically be created.
+
+For example, you could add a new Introduction page by updating the SUMMARY.md to the following.
+
+```markdown
+# Summary
+
+- [Introduction](./intro.md)
+- [Chapter 1](./chapter_1.md)
+```
+
+This will automatically create a new `intro.md` file with the title of Introduction. This will also update the table of contents and allow you to move between the Introduction and Chapter 1 pages by way of arrows on screen, and on the keyboard.
+
+```bash
+git add .
+git commit -m "Add message summary"
+```

src/step_3.md

@@ -0,0 +1,11 @@
+# Step 3: Editing content
+If you want to edit content simply open the Markdown file you want to change and edit the content.
+
+If you still have `mdbook.exe serve` up and running, the browser will automatically be updated when you save the content.
+
+If you want to change the file name of a page, your best bet is to update the SUMMARY.md file and then move your content over. Alternatively you can stop mdbook.exe and it won't helpfully create files that don't exist.
+
+```bash
+git add .
+git commit -m "Update message summary"
+```

src/step_4.md

@@ -0,0 +1,24 @@
+# Step 4: GitLab repository
+Since we're going to use GitLab to host the site via [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/), we'll need to create a new repository for the book.
+
+> You could have optionally done this as part of the initial setup, and then cloned the new repository and initialized mdBook.
+
+Log into GitLab and create a new project/repository.
+
+Since we already initialized the Git repo locally we can create a blank project.
+
+> Alternatively, you could also use GitHub as your primary source and then use the Run CI/CD for external repository option here. This option works best if the repository is public.
+
+Give the project a name, update the project slug if needed, provide a project description if you'd like, and set the (code) visibility level. If you've run `git init` locally you'll want to make sure you uncheck the "Initialize repository with a README" option.
+
+You'll now have a GitLab repository that we can hook up to our local repo.
+
+## Adding the remote to our local repo
+We can use a combination of the commands under the "Push an existing folder" and "Push an existing Git repository" headings that GitLab provides to update our local repo and push it to GitLab.
+
+Update the URL (`https://gitlab.com/strivinglife/book-gitlab-mdbook.git`) and branch name (`main`) as needed.
+
+```bash
+git remote add origin https://gitlab.com/strivinglife/book-gitlab-mdbook.git
+git push -u origin main
+```

src/step_6.md

@@ -0,0 +1,30 @@
+# Step 6: gitlab-ci
+Once you have your book in a fairly good state, or are otherwise ready to start publishing it to GitLab Pages, you can create a GitLab CI file.
+
+In the root of your book's directory create a new .gitlab-ci.yml file with the following contents:
+
+```yml
+stages:
+    - deploy
+
+pages:
+  stage: deploy
+  image: rust:latest
+  variables:
+    CARGO_HOME: $CI_PROJECT_DIR/cargo
+  before_script:
+    - export PATH="$PATH:$CARGO_HOME/bin"
+    - mdbook --version || cargo install --debug mdbook
+  script:
+        - mdbook build -d public
+  only:
+      - master 
+  artifacts:
+      paths:
+          - public
+  cache:
+    paths:
+    - $CARGO_HOME/bin
+```
+
+Using the latest Rust image, this will setup Cargo, make sure mdBook is installed, and then use it to build the book to a public directory. This public directory will then be used by GitLab Pages.

src/tweaks/toml.md

@@ -0,0 +1,22 @@
+# Step 5: Book TOML
+The book.toml file contains basic information about your book.
+
+You can generally get by fine with the default contents, but you may want to tweak the file.
+
+## output.html
+Depending upon the audience of your book, you may want to link to the Git repository.
+
+The following two changes, added to the end of the book.toml file, will add a link to the Git repository and the page to edit the Markdown file that generates the current page.
+
+> Update the repository URL and branch name, in `edit-url-template`, as needed.
+
+```toml
+[output.html]
+git-repository-url = "https://gitlab.com/strivinglife/book-gitlab-mdbook"
+edit-url-template = "https://gitlab.com/strivinglife/book-gitlab-mdbook/-/edit/main/{path}"
+git-repository-icon = "fa-gitlab"
+```
+
+> The Git repository URL will use the GitHub icon by default, even if you link to a non-GitHub page. `git-repository-icon` can be used to override that default, as shown above.
+
+There are other options, detailed in the [Configuration section of the mdBook Documentation](https://rust-lang.github.io/mdBook/format/configuration/index.html).