diff --git a/README.md b/README.md index bd7e953bf6111506a4e2227e59b3b1e2ae72ee27..90bf88e8e0ba051daa95622686dbd7cb4829c827 100644 --- a/README.md +++ b/README.md @@ -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 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. -3. Edit [index.Rmd](blob/master/index.Rmd) and change any fields, - like: `title:`, `author:`, `date:`, `url:` and `description:`. +3. Edit `index.Rmd` and change any fields, like: `title:`, `author:`, + `date:`, `url:` and `description:`. -4. Edit [_bookdown.yml](blob/master/_bookdown.yml) and change the - field `book_filename:`. +4. Edit `_bookdown.yml` and change the field `book_filename:`. 5. Change and modify the `*.md` files, and don't forget to update - [_bookdown.yml](blob/master/_bookdown.yml) as well with the names - of the new files. + `_bookdown.yml` as well with the names of the new files. 6. Optionally, you may also experiment with changing the look and - layout of the book by customizing - [index.Rmd](blob/master/index.Rmd). For more details about the - available options make sure to read: + layout of the book by customizing `index.Rmd`. For more details + about the available options make sure to read: - https://bookdown.org/yihui/bookdown/html.html - https://bookdown.org/yihui/bookdown/yaml-options.html @@ -37,9 +34,9 @@ changes to the GitLab project automatically published and updated on the URL address `https://<username>.gitlab.io/<book-title>/`. How does it happen? -The key to understanding this is the file -[.gitlab-ci.yml](blob/master/.gitlab-ci.yml), which has a content like -this: +The key to understanding this is the file `.gitlab-ci.yml`, which has +a content like this: + ```yml image: dockerscripts/bookdown @@ -53,7 +50,7 @@ pages: - 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 is updated (for example some commits are pushed or a _Merge Request_ is accepted). @@ -72,17 +69,17 @@ to do it. Basically, in plain English, it says something like this: that is expected to be published), - then get the content of the directory `public/` and publish it on 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 -CI/CD jobs, whether they passed or failed, etc. This can be very +You can check the page "CI/CD -> Pipelines" to see more details about +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 the log messages and hopefully find out what was the problem. ## How to add a custom domain 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 http://dashohoxha.gitlab.io/101-problema-programimi/ I have used as @@ -175,7 +172,7 @@ on GitHub. You can do it like this: ``` 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 cd books/bookdown-example/ @@ -188,16 +185,16 @@ on GitHub. You can do it like this: 4. Go to your repository’s settings and under "GitHub Pages" change the "Source" to be "master branch /public folder" (as described in - [GitHub - help](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)). + this [GitHub help + 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 the `public/` directory with `ds render books/bookdown-example/`, and to commit and push its changes to GitHub. 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 -the markdown files are commited and pushed to GitHub. This automated +which would update the website of the book whenever some changes to +the markdown files are committed and pushed to GitHub. This automated way is described in this [help page](https://bookdown.org/yihui/bookdown/github.html). However it a bit complex and maybe not worth the trouble. @@ -213,10 +210,9 @@ useful for math. These extension are described on this page: https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html 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$`, -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 -[render.sh](blob/master/render.sh), so that markdown files are -rendered nicely both on the GitLab web interface and on the website of -the book. +`render.sh`, so that markdown files are rendered nicely both on the +GitLab web interface and on the website of the book.