<p><div><div><div><div data-show-faces="false" data-height="21" data-width="100" data-layout="button_count" data-send="true" data-href="https://www.r-bloggers.com/building-a-website-with-pkgdown-a-short-guide/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://lbusettspatialr.blogspot.com/2017/08/building-website-with-pkgdown-short.html"> Spatial Processing in R</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p>As promised in my <a rel="nofollow" href="http://lbusettspatialr.blogspot.it/2017/07/the-new-modistsp-website-based-on.html" target="_blank">last post</a>, here is a short guide with some <b>tips and tricks for building a documentation website</b> for an <span><b>R</b></span> package using <span><b>pkgdown</b></span>.</p>
<p>In the end, this guide ended up way longer than I was expecting, but I hope you’ll find it useful, although it often replicates information already available in <span><b>pkgdown</b></span> documentation !</p>
<h2><span>Prerequisites</span></h2>
<div></div>
<div>
<div>To build a website using <span><b>pkgdown</b></span>, all you need to have is an <span><b>R</b></span> package <b>hosted on Git Hub</b>, with a file structure “tweaked” with some functionality provided by <span><b>devtools</b></span>. </div>
<div></div>
<div>Assuming you are using RStudio, and that you didn’t already do this, open the project corresponding to your package and (as a minimum) run:</div>
</div>
<div></div>
<div>
<pre><code><span>require</span>(devtools)<br><span>use_readme_rmd</span>()<br><span>use_news_md</span>()<br><span>use_vignette</span>(<span>&quot;test&quot;</span>)  <span>#substitute with the name of your package</span></code></pre>
</div>
<div>
<p><a name="more"></a>Since to use <span><b>pkgdown</b> </span>your package must be on Git Hub, you may also want: </div>
<div></div>
<div>
<pre><code><span>use_github_links</span>()</code></pre>
</div>
<div>
<div>, which will populate automatically some fields in the <span><b>DESCRIPTION</b></span> file successively used to build the home page of your website.</div>
<div></div>
<div>Other possibly useful commands (depending on the status of your package) may be: </div>
</div>
<div></div>
<div>
<pre><code><span>use_travis</span>()<br><span>use_cran_badge</span>()  </code></pre>
</div>
<div>(see <span><b>devtools</b></span> documentation for further info)</div>
<div></div>
<p>At this point, within your package file structure you should have a <b>README.Rmd </b>file (which is used also to create the “README.md” file for Git Hub), and a <b>NEWS.md</b> file. You should also have a <i><b>man </b></i>subfolder containing the <i>.Rd</i> files documenting your functions (usually auto-generated from roxygen comments using <span><b>devtools::document()</b></span>). Finally, you should have a <b>my_package.Rmd</b> file in the <i>vignettes </i>subfolder (which is used for example by <span><b>devtools::build_vignette()</b></span> to automatically create a vignette for the package).</p>
<h2><span>Getting Started: creating a bare-bones website</span></h2>
<p>To create a standard <span><b>pkgdown</b></span> site, just run:</p>
<pre><code>devtools<span>::</span><span>install_githb</span>(<span>&quot;hadley/pkgdown&quot;</span>)<br><span>library</span>(pkgdown)<br><span>build_site</span>()</code></pre>
<p><span><b>build_site()</b></span> will do several things:
<ul>
<li><b>create a “docs” subfolder</b> in your file structure, where it will place all the material needed for rendering the website;</li>
<li><b>knit README.Rmd</b> to “docs/index.html”. This will be the home page of your website;</li>
<li><b>knit NEWS.md</b> to “docs/news/index.html” (in this way, any time you update NEWS.md, the news section of the website can be automatically updates);</li>
<li><b>knit all your “Rd” files </b>to “docs/reference/” as html files inheriting the name of the function (e.g., “docs/reference/myfun_1.html” “docs/reference/myfun_2.html”, etc.). A “docs/reference/index.html” page is also created: this is a simple html page linking to the html documentation pages for the different functions (see for example here). <i>By default, all functions will be included and listed in alphabetical order</i>.</li>
<li><b>knit any Rmd files in your “vignettes” subfolder</b> to “docs/articles” as single html files;</li>
<li><b>Scrape your package for various other info </b>(e.g., Authors, Git Hub address, License, Citation, badges, etc.) to create additional material on the right-hand side bar of the home page;</li>
<li><b>Put everything together </b>by some magic to build a working website, and open a preview in RStudio Viewer or your browser.</li>
</ul>
<p>The resulting website will look more or less like this:</p>
<table cellspacing="0" align="center" cellpadding="0">
<tbody>
<tr>
<td><a rel="nofollow" href="https://i1.wp.com/4.bp.blogspot.com/-ZsW3DY2tBk0/WYA4CmkMWAI/AAAAAAAACIs/111xlxU0AEUhzaZl54vkGAEI4o-ddoW5wCLcBGAs/s1600/Capture.PNG?ssl=1" target="_blank"><img border="0" data-original-height="862" src="https://i0.wp.com/4.bp.blogspot.com/-ZsW3DY2tBk0/WYA4CmkMWAI/AAAAAAAACIs/111xlxU0AEUhzaZl54vkGAEI4o-ddoW5wCLcBGAs/s640/Capture.PNG?resize=450%2C862&ssl=1" data-recalc-dims="1" data-original-width="450"></a></td>
</tr>
<tr>
<td>“Standard” website built by pkgdown::build_site()</td>
</tr>
</tbody>
</table>
<p>, with your main vignette linked in <b>Getting Started</b>, and all the other Rmds found in <i>vignettes</i> (if any) linked-to in the <b>Articles</b> drop down menu.</p>
<p>Considering that <b>all is needed is to run </b><span><b>build_site()</b> </span>(in particular if the package is already using devtools tweaks), I’d say that this is already a nice result ! However, spending some time in better configuring the structure of the site and tweaking some small things allows to achieve a much nicer result, as explained below.</p>
<h2><span>Customizing appearence and structure of the website: the _pkgdown.yaml file</span></h2>
<p>Your <span>pkgdown</span> website can be further customized by <b>creating and customizing a text file named <i>_pkgdown.yaml</i> in the root folder of your project</b>. The file needs to have three main sections, which I will describe here using the current <i>.yaml</i> file used in the MODIStsp Website as an example (the complete file can be found <a rel="nofollow" href="https://github.com/lbusett/MODIStsp/blob/devel/_pkgdown.yaml" target="_blank">here</a>).</p>
<h3><u><span>Preamble Section</span></u></h3>
<p>This is quite straightforward: first of all, give a title to your website and provide its URL. Then, <b>select a template to customize its appearance</b> from the ones available at <a rel="nofollow" href="https://bootswatch.com/" target="_blank">bootswatch</a>. Finally, add the GoogleAnalytics tracking code if you wish.</p>
<pre><code>title: MODIStsp<br>url: http://lbusett.github.io/MODIStsp<br>template:<br>  params:<br>    bootswatch: flatly<br>    ganalytics: UA-12345678-0</code></pre>
<p>
<h3><u><span>Reference Section</span></u></h3>
<p>Here, you can configure the page of the website <b>containing the index to the documentation of your functions</b> (<i>docs/reference/index.html</i>). Instead than having a simple list in alphabetical order, you can <b>define different groups and decide which functions to put in each group</b>.</p>
<p>Each group is defined by a <b>title</b>, a <b>description </b>(use ~ for no description), and a <b>contents section</b> containing an indented list of functions to be included in that group. Syntax and indentation rules <b>must be strictly followed but are very simple.</b> Looking at the example below should suffice for understanding it. In this case I decided to use only two groups: one for exported functions, and one for everything else, but you can set-up as many groups as you need.</p>
<pre><code>reference:<br>  - title: Exported Functions<br>    desc: Functions exported by MODIStsp<br>    contents:<br>      - '`MODIStsp`'<br>      - '`MODIStsp_extract`'<br>      - '`MODIStsp_addindex`'<br>      - '`install_MODIStsp_launcher`'<br>  - title: Internals<br>    desc: Internal functions and helpers<br>    contents:<br>      - '`MODIStsp_GUI`'<br>      - '`MODIStsp_process`'<br>      - '`MODIStsp_process_indexes`'<br>      - '`MODIStsp_process_QA_bits`'<br>      - '`MODIStsp_read_xml`'<br>      - '`lpdaac_getmod_dirs`'<br>      - '`lpdaac_getmod_dates`'<br>      - '`lpdaac_getmod_names`'<br>      - '`MODIStsp_check_files`'<br>      - '`MODIStsp_vrt_create`'<br>      - '`bbox_from_file`'<br>      - '`reproj_bbox`'</code></pre>
<h3><u><span>Navbar Section</span></u></h3>
<p>The last section of <i>_pkgdown.yaml</i> is named <b>navbar</b>, and is where most the customization occurs.</p>
<p>In the first line, you can choose if using a <b>standard or inverse color scheme</b> for your boootstrap template. The only way to understand what this does is to try both and see which one you do prefer.</p>
<pre><code>navbar:<br>  type: inverse</code></pre>
<p>Next, you can define what content will be accessible through <b>buttons or menus on the left side</b> of the top-menu of the website.</p>
<ul>
<li><b>Buttons </b>linking to a single page are described by:</li>
</ul>
<ol>
<ol>
<li>a <b>title text or an icon name</b> (chosen from <a rel="nofollow" href="http://fontawesome.io/icons/" target="_blank">http://fontawesome.io/icons/</a>) that will be shown on the button;</li>
<li>a <b>hyperlink </b>to the page that will be accessed through the button (Note that the hyperlinks are built relative to the root of the “docs” folder created by pkgdown – no need to specify full paths !).</li>
</ol>
</ol>
<ul>
<li><b>Dropdown menus</b> giving access to multiple pages are described by:</li>
</ul>
<ol>
<ol>
<li>a <b>title text or an icon name</b>;</li>
<li>a “menu:” line;  </li>
<li>an indented <b>list of the text entries</b> that will appear in the menu, <i>with the associated hyperlinks</i>.</li>
</ol>
</ol>
<p>In the example below, you can see <b>how the content should be indented and organized:</b></p>
<pre><code>  left:<br>    - icon: fa-home<br>      href: index.html<br>    - text: &quot;How To&quot;<br>      menu: <br>      -  text: Installation<br>         href: articles/installation.html<br>      -  text: Interactive Execution - the MODIStsp GUI<br>         href: articles/interactive_execution.html<br>      -  text: Non-Interactive Execution from within R<br>         href: articles/noninteractive_execution.html<br>      -  text: Standalone Execution and Scheduled Processing<br>         href: articles/standalone_execution.html<br>      -  text: Outputs Format and Naming Conventions<br>         href: articles/output.html<br>      -  text: Accessing and Analyzing Processed Data from R<br>         href: articles/analyze.html<br>    - text: &quot;Examples of Use&quot;<br>      href: articles/examples.html</code></pre>
<p>In the case of MODIStsp website, I decided to not provide a link to the “full” vignette (which was linked from “Getting Started” in the “bare-bones” website). Instead, I <b>divided the contents of that vignette in six shorter articles accessible from the “How To” dropdown menu</b>.</p>
<p>To do that, I just had to <b>create six separate Rmd files within the vignettes folder</b>. All Rmds within that folder are automatically knitted by pkgdown when launching either <span><b>build_site()</b> </span>or <span><b>build_articles()</b></span>, and are therefore available for linking from the menu.</p>
<p>Finally, in the last section of <i>_pkgdown.yaml</i> you can specify what content should be accessible from the <b>right-hand side of the top menu</b>. Syntax and indentation are identical to what described above.</p>
<pre><code> right:<br>    - text: &quot;faq&quot;<br>      icon: fa-question-circle-o<br>      href: articles/faq.html<br>    - icon: fa-newspaper-o<br>      text: &quot;news&quot;<br>      href: news/index.html<br>    - icon: fa-file-code-o <br>      text: &quot;functions&quot;<br>      href: reference/index.html<br>    - icon: fa-github fa-lg<br>      text: &quot;github&quot;<br>      href: https://github.com/lbusett/MODIStsp/</code></pre>
<p><span>In MODIStsp website, we are using the right side of the top menu bar to provide access to:</span><br><span><br></span>
<ul>
<li><span><b>a static page</b> containing a FAQ; </span></li>
<li><span>the <b>auto-generated news page</b> (by linking to news/index.html); </span></li>
<li><span><b>the function documentation index page </b>(by linking to reference/index.html); </span></li>
<li><span>an icon linking to the MODIStsp repository on Git Hub. </span></li>
</ul>
<p><i><span>(From the example, you can see that it is possible to associate the “buttons” including wit both an icon and a short title text. In that case, the icon and the text will are shown one after the other.)</span></i></p>
<p>Once your .yaml file is complete, just<b> run </b><span><b>build_site()</b></span><b> again </b>and check the results. Then iterate ad-libitum until you are satisfied by the resulting structure.</p>
<h2><span>Fine tuning</span></h2>
<div></div>
<p>When you are satisfied with the structure of the website, you can start <b>tweaking its contents</b> to achieve a better-looking final result. Here I’m just <b>sharing some tips and tricks </b>I learnt while building our website:</p>
<ul>
<li>If (like me) you wish to have <b>a different “home page” in the website and in the main Git Hub page</b>, you can create a new <i>index.Rmd</i> file in the root of the package. If <i>index.Rmd</i> is found, it is used instead than <i>README.Rmd </i>to populate the home page;</li>
</ul>
<ul>
<li>Text in the “standard” output is <b>a bit too “compressed”</b> for my taste. You can <b>increase the spacing between the main sections</b> of an article by simply adding a <br> at the end of each main section;</li>
</ul>
<ul>
<li>Similarly, you can <b>add line separators between section</b>s by simply adding a line of underscores under each section;</li>
</ul>
<ul>
<li>To reduce the “wall of text” effect, you can <b>put any of the <a rel="nofollow" href="http://fontawesome.io/icons/" target="_blank">http://fontawesome.io/icons/</a> icons in an article</b> by inserting its “full html specification” in the text of the corresponding Rmd. (For example,”I want a github icon here: <i> class=”fa fa-github aria-hidden=”true”></i>” would render in the website with a “Git Hub octopus” icon at the end);</li>
</ul>
<ul>
<li>Of course, you can <b>add any image/R plot by</b> linking/creating it in the <i>Rmds </i>of the different articles or of the home page;</li>
</ul>
<ul>
<li>If you build the site using<b> </b><span><b>build_site(run_dont_run = TRUE)</b></span>, the examples with the “dont_run” specification in the roxygen comment will be run, and their results appear in the documentation page of each function. I find this really <b>useful to illustrate the typical behaviour of functions;</b></li>
</ul>
<ul>
<li>To <b>provide modifiers to the standard pkgdown.css and pkgdown.js files</b>, create a new folder named “<i><span>pkgdown</span></i>” in your project root. As described in pkgdown documentation, “<i>the content of files “extra.css and “extra.js” placed in this folder will be copied to docs/ and inserted into the </i></ul>