Skip to content
Snippets Groups Projects
Commit c67c5e08 authored by Dashamir Hoxha's avatar Dashamir Hoxha
Browse files

Fix and update README

parent 701ecb16
Branches
No related tags found
No related merge requests found
...@@ -9,23 +9,20 @@ This is a minimal example of a book based on R Markdown and ...@@ -9,23 +9,20 @@ This is a minimal example of a book based on R Markdown and
the address `https://<username>.gitlab.io/bookdown-example/`. For the address `https://<username>.gitlab.io/bookdown-example/`. For
more details on how this works check the next section. more details on how this works check the next section.
2. Go to the [settings](edit) of the projects and change the "Project 2. Go to the "Settings" of the projects and change the "Project
name". Expand the "Advanced" section and change the path as well. name". Expand the "Advanced" section and change the path as well.
3. Edit [index.Rmd](blob/master/index.Rmd) and change any fields, 3. Edit `index.Rmd` and change any fields, like: `title:`, `author:`,
like: `title:`, `author:`, `date:`, `url:` and `description:`. `date:`, `url:` and `description:`.
4. Edit [_bookdown.yml](blob/master/_bookdown.yml) and change the 4. Edit `_bookdown.yml` and change the field `book_filename:`.
field `book_filename:`.
5. Change and modify the `*.md` files, and don't forget to update 5. Change and modify the `*.md` files, and don't forget to update
[_bookdown.yml](blob/master/_bookdown.yml) as well with the names `_bookdown.yml` as well with the names of the new files.
of the new files.
6. Optionally, you may also experiment with changing the look and 6. Optionally, you may also experiment with changing the look and
layout of the book by customizing layout of the book by customizing `index.Rmd`. For more details
[index.Rmd](blob/master/index.Rmd). For more details about the about the available options make sure to read:
available options make sure to read:
- https://bookdown.org/yihui/bookdown/html.html - https://bookdown.org/yihui/bookdown/html.html
- https://bookdown.org/yihui/bookdown/yaml-options.html - https://bookdown.org/yihui/bookdown/yaml-options.html
...@@ -37,9 +34,9 @@ changes to the GitLab project ...@@ -37,9 +34,9 @@ changes to the GitLab project
automatically published and updated on the URL address automatically published and updated on the URL address
`https://<username>.gitlab.io/<book-title>/`. How does it happen? `https://<username>.gitlab.io/<book-title>/`. How does it happen?
The key to understanding this is the file The key to understanding this is the file `.gitlab-ci.yml`, which has
[.gitlab-ci.yml](blob/master/.gitlab-ci.yml), which has a content like a content like this:
this:
```yml ```yml
image: dockerscripts/bookdown image: dockerscripts/bookdown
...@@ -53,7 +50,7 @@ pages: ...@@ -53,7 +50,7 @@ pages:
- master - master
``` ```
This file instructs the CI/CD (Continuos Integration and Development) This file instructs the CI/CD (Continuous Integration and Development)
system of GitLab to do something whenever the content of the project system of GitLab to do something whenever the content of the project
is updated (for example some commits are pushed or a _Merge Request_ is updated (for example some commits are pushed or a _Merge Request_
is accepted). is accepted).
...@@ -72,17 +69,17 @@ to do it. Basically, in plain English, it says something like this: ...@@ -72,17 +69,17 @@ to do it. Basically, in plain English, it says something like this:
that is expected to be published), that is expected to be published),
- then get the content of the directory `public/` and publish it on - then get the content of the directory `public/` and publish it on
the website of the project the website of the project
(`https://<username>.gitlab.io/<book-title>/`). `https://<username>.gitlab.io/<book-title>/`
You can check the [Pipelines](pipelines) to see more details about the You can check the page "CI/CD -> Pipelines" to see more details about
CI/CD jobs, whether they passed or failed, etc. This can be very the CI/CD jobs, whether they passed or failed, etc. This can be very
useful especially when a job has failed, because you can also check useful especially when a job has failed, because you can also check
the log messages and hopefully find out what was the problem. the log messages and hopefully find out what was the problem.
## How to add a custom domain ## How to add a custom domain
If you want to use a custom domain for the book you can do this from If you want to use a custom domain for the book you can do this from
[Settings / Pages](pages). "Settings -> Pages".
For example for the book For example for the book
http://dashohoxha.gitlab.io/101-problema-programimi/ I have used as http://dashohoxha.gitlab.io/101-problema-programimi/ I have used as
...@@ -175,7 +172,7 @@ on GitHub. You can do it like this: ...@@ -175,7 +172,7 @@ on GitHub. You can do it like this:
``` ```
3. Remove the file `.gitignore` which prevents the directory `public/` 3. Remove the file `.gitignore` which prevents the directory `public/`
from being commited to Git, and commit this directory to Git: from being committed to Git, and commit this directory to Git:
```bash ```bash
cd books/bookdown-example/ cd books/bookdown-example/
...@@ -188,16 +185,16 @@ on GitHub. You can do it like this: ...@@ -188,16 +185,16 @@ on GitHub. You can do it like this:
4. Go to your repository’s settings and under "GitHub Pages" change 4. Go to your repository’s settings and under "GitHub Pages" change
the "Source" to be "master branch /public folder" (as described in the "Source" to be "master branch /public folder" (as described in
[GitHub this [GitHub help
help](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)). page](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)).
To update the page, after making some changes, you have to regenerate To update the page, after making some changes, you have to regenerate
the `public/` directory with `ds render books/bookdown-example/`, and the `public/` directory with `ds render books/bookdown-example/`, and
to commit and push its changes to GitHub. to commit and push its changes to GitHub.
It is also possible to build an auto-update system with Travis CI, It is also possible to build an auto-update system with Travis CI,
which whould update the website of the book whenever some changes to which would update the website of the book whenever some changes to
the markdown files are commited and pushed to GitHub. This automated the markdown files are committed and pushed to GitHub. This automated
way is described in this [help way is described in this [help
page](https://bookdown.org/yihui/bookdown/github.html). However it a page](https://bookdown.org/yihui/bookdown/github.html). However it a
bit complex and maybe not worth the trouble. bit complex and maybe not worth the trouble.
...@@ -213,10 +210,9 @@ useful for math. These extension are described on this page: ...@@ -213,10 +210,9 @@ useful for math. These extension are described on this page:
https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html
Besides these, the syntax of GitLab markdown is a bit different from Besides these, the syntax of GitLab markdown is a bit different from
that of Pandoc's Markdown. For example the delimiters of the math code that of Pandoc's Markdown. For example the delimiter of the math code
on Pandoc's Markdown is a single dollar sign, like this: `$a^2$`, on Pandoc's Markdown is a single dollar sign, like this: `$a^2$`,
while that delimiter for GitLab Markdown is like this: `$\`a^2\`$`. while that delimiter for GitLab Markdown is like this: ``$`a^2`$``.
These small differences are fixed automatically by the script These small differences are fixed automatically by the script
[render.sh](blob/master/render.sh), so that markdown files are `render.sh`, so that markdown files are rendered nicely both on the
rendered nicely both on the GitLab web interface and on the website of GitLab web interface and on the website of the book.
the book.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment