1 Introduction

This Community Guide, written in Bookdown, is intended for Delinea Professional Services and their customers to assist with unique tasks or “how-tos” that are not covered in official training. Articles are written by Delinea Professional Services consultants and architects from real-world experiences so it should serve as a great resource for everyone.

In addition to being an online resource, this format will also be exported into a .pdf file for offline viewing.

1.1 How to add an article

This section will describe the process to create the file and folder structure needed to contribute an article to the project.

1.1.1 File/Folder Structure

To contribute an article, create a folder named after your article. Then convert the name of the folder to lowercase and replace all spaces with a hyphen -. For example, if your article name is How to install XYZ, then the folder should be named how-to-install-xyz.

Inside that folder, create a new RMarkdown .Rmd file. This file should also follow the same naming convention mentioned above. Continuing with the same example, if your article name is How to install XYZ, then the RMarkdown file should be named how-to-install-xyz.Rmd.

This should create a file/folder structure that looks like the following:

how-to-install-xyz\how-to-install-xyz.Rmd

This is the bare minimum needed for a proper article contribution to this project. Any supporting graphics or other files should also go into this folder. Supporting files do not need to follow this special naming convention.

1.1.2 RMarkdown File Structure

The RMarkdown file needs to follow a simple format for proper inclusion into the project. There just needs to be a single, level 1 header # at the top of the document. You can use standard Markdown or RMarkdown syntax for whatever you wish to document. Continuing with the same example from above, the .Rmd file should look like the following:

# How to install XYZ

This article is to show how to install XYZ.

## Step 1

This is a second level header for my article.

1.1.3 Including Graphics

While Markdown has a syntax for inserting graphics, it is recommended to use the following to ensure full compatibility with both web and pdf forms of this Bookdown project.

To insert fully compatible graphics, the following syntax should be used; continuing from our earlier example:

```{r echo=FALSE, fig.cap="Graphic Caption", out.width = '75%', fig.align='center', fig.pos = 'H'}
knitr::include_graphics("articles/how-to-install-xyz/Example Graphic.png")
```

1.1.4 Updating _bookdown.yml

Once all the files for your article are in the proper format, there needs to be a change to the base _bookdown.yml file in the root project folder. This file controls meta data about the Bookdown’s project structure.

The part that needs to be updated is a line for the property rmd_files. This array controls the listing of the Rmd articles in order as it appears in this array. For example, let’s take a look at a basic version of the property with just the index.Rmd file and another article.

rmd_files: [
  "index.Rmd",
  "articles/how-to-configure-abc/how-to-configure-abc.Rmd"
]

To include your article in the Bookdown project, simply add a line to this file, separated by a comma and included in quotes. To continue from our earlier example, the following is adding the “How to Install XYZ” article into this property:

rmd_files: [
  "index.Rmd",
  "articles/how-to-configure-abc/how-to-configure-abc.Rmd",
  "articles/how-to-install-xyz/how-to-install-xyz.Rmd"
]

Once these changes are made to _bookdown.yml, submit these changes as a pull request to the Bookdown project. Once these changes are merged your article should now appear as part of the project.