Skip to content
Permalink
Browse files

more yihui.name -> yihui.org

  • Loading branch information
yihui committed Nov 18, 2019
1 parent 3272cfd commit e9b81b22ece008d02370fd351ff24db7b552c1e4
@@ -88,7 +88,7 @@

- Added a new RStudio addin "Touch File" to update the modification time of a file, which can be useful when you want to force rebuilding a certain Rmd post after running `serve_site()` (#294).

- Added an RStudio addin "Quote Poem" to quote a poem using the Markdown syntax (https://yihui.name/en/2018/06/quote-poem-blogdown/).
- Added an RStudio addin "Quote Poem" to quote a poem using the Markdown syntax (https://yihui.org/en/2018/06/quote-poem-blogdown/).

- Added a new function `shortcodes()`, which is a vectorized version of `shortcode()`. For example, you can embed multiple tweets (thanks, @maelle, #307).

@@ -8,7 +8,7 @@ Hopefully, you can better see why you should have a website now.

## Yihui Xie {-}

Yihui Xie (<https://yihui.name>) is a software engineer at RStudio (<https://www.rstudio.com>). He earned his PhD from the Department of Statistics, Iowa State University. He is interested in interactive statistical graphics and statistical computing. As an active R user, he has authored several R packages, such as **knitr**, **bookdown**, **blogdown**, **xaringan**, **animation**, **DT**, **tufte**, **formatR**, **fun**, **mime**, **highr**, **servr**, and **Rd2roxygen**, among which the **animation** package won the 2009 John M. Chambers Statistical Software Award (ASA). He also co-authored a few other R packages, including **shiny**, **rmarkdown**, and **leaflet**.
Yihui Xie (<https://yihui.org>) is a software engineer at RStudio (<https://www.rstudio.com>). He earned his PhD from the Department of Statistics, Iowa State University. He is interested in interactive statistical graphics and statistical computing. As an active R user, he has authored several R packages, such as **knitr**, **bookdown**, **blogdown**, **xaringan**, **animation**, **DT**, **tufte**, **formatR**, **fun**, **mime**, **highr**, **servr**, and **Rd2roxygen**, among which the **animation** package won the 2009 John M. Chambers Statistical Software Award (ASA). He also co-authored a few other R packages, including **shiny**, **rmarkdown**, and **leaflet**.

In 2006, he founded the Capital of Statistics (<https://cosx.org>), which has grown into a large online community on statistics in China. He initiated the Chinese R conference in 2008, and has been involved in organizing R conferences in China since then. During his PhD training at Iowa State University, he won the Vince Sposito Statistical Computing Award (2011) and the Snedecor Award (2012) in the Department of Statistics.

@@ -179,7 +179,7 @@ if (file.exists('~/.Rprofile')) {
# then set options(blogdown.author = 'Your Name') in ~/.Rprofile
```

Note that [R will silently ignore the last line of your `.Rprofile`](https://yihui.name/en/2018/04/rprofile-trailing-newline/) if it does not have a trailing newline, so please make sure you add at least one newline to the end of your `.Rprofile`.
Note that [R will silently ignore the last line of your `.Rprofile`](https://yihui.org/en/2018/04/rprofile-trailing-newline/) if it does not have a trailing newline, so please make sure you add at least one newline to the end of your `.Rprofile`.

## R Markdown vs. Markdown {#output-format}

@@ -332,7 +332,7 @@ You can learn more about Hugo templates from the official documentation (https:/

### A minimal example

[XMin](https://github.com/yihui/hugo-xmin) is a Hugo theme\index{XMin Theme} I wrote from scratch in about 12 hours. Roughly half an hour was spent on templates, 3.5 hours were spent on tweaking the CSS styles, and 8 hours were spent on the documentation (https://xmin.yihui.name). I think this may be a representative case of how much time you would spend on each part when designing a theme. It is perhaps our nature to spend much more time on cosmetic stuff like CSS than essential stuff like templates. Meanwhile, coding is often easier than documentation.
[XMin](https://github.com/yihui/hugo-xmin) is a Hugo theme\index{XMin Theme} I wrote from scratch in about 12 hours. Roughly half an hour was spent on templates, 3.5 hours were spent on tweaking the CSS styles, and 8 hours were spent on the documentation (https://xmin.yihui.org). I think this may be a representative case of how much time you would spend on each part when designing a theme. It is perhaps our nature to spend much more time on cosmetic stuff like CSS than essential stuff like templates. Meanwhile, coding is often easier than documentation.

We will show the source code of the XMin theme. Because the theme may be updated occasionally in the future, you may follow this link to obtain a fixed version that we will talk about in this section: https://github.com/yihui/hugo-xmin/tree/4bb305. Below is a tree view of all files and directories in the theme:

@@ -447,7 +447,7 @@ To understand `layouts/`, you must know some basics about HTML (see Section \@re
</main>
```

For a full example of a single page, you may see https://xmin.yihui.name/about/.
For a full example of a single page, you may see https://xmin.yihui.org/about/.

- `list.html` is the template\index{list.html} for rendering lists of pages, such as a list of blog posts, or a list of pages within a category or tag. Here is its source code:

@@ -478,9 +478,9 @@ To understand `layouts/`, you must know some basics about HTML (see Section \@re

Next we generate the list using a loop (`range`) through all pages filtered by the condition that the section of a page should not be empty. "Section" in Hugo means the first-level subdirectory name under `content/`. For example, the section of `content/post/foo.md` is `post`. Therefore the filter means that we will list all pages under subdirectories of `content/`. This will exclude pages under the root `content/` directory, such as `content/about.md`.

Please note that the variable `.Data` is dynamic, and its value changes according to the specific list you want to generate. For example, the list page https://xmin.yihui.name/post/ only contains pages under `content/post/`, and https://xmin.yihui.name/note/ only contains pages under `content/note/`. These list pages are automatically generated by Hugo, and you do not need to explicitly loop through the sections `post` and `note`. That is, a single template `list.html` will generate multiple lists of pages according to the sections and taxonomy terms (e.g., categories and tags) you have on your website.
Please note that the variable `.Data` is dynamic, and its value changes according to the specific list you want to generate. For example, the list page https://xmin.yihui.org/post/ only contains pages under `content/post/`, and https://xmin.yihui.org/note/ only contains pages under `content/note/`. These list pages are automatically generated by Hugo, and you do not need to explicitly loop through the sections `post` and `note`. That is, a single template `list.html` will generate multiple lists of pages according to the sections and taxonomy terms (e.g., categories and tags) you have on your website.

The list items are represented by the HTML tags `<li>` in `<ul>`. Each item consists of the date, link, and title of a page. You may see https://xmin.yihui.name/post/ for a full example of a list page.
The list items are represented by the HTML tags `<li>` in `<ul>`. Each item consists of the date, link, and title of a page. You may see https://xmin.yihui.org/post/ for a full example of a list page.

- `terms.html` is the template\index{terms.html} for the home page of taxonomy terms. For example, you can use it to generate the full list of categories or tags. The source code is below:

@@ -505,7 +505,7 @@ To understand `layouts/`, you must know some basics about HTML (see Section \@re

Similar to `list.html`, it also uses a loop. The variable `.Data.Terms` stores all terms under a taxonomy, e.g., all category names. You can think of it as a named list in R (called a `map` in Go), with the names being the terms and the values being lists of pages. The variable `$key` denotes the term and `$value` denotes the list of pages associated with this term. What we render in each `<li>` is a link to the term page as well as the count of posts that used this term (`len` is a Go function that returns the length of an object).

Hugo automatically renders all taxonomy pages, and the path names are the plural forms of the taxonomies, e.g., https://xmin.yihui.name/categories/ and https://xmin.yihui.name/tags/. That is the meaning of `.Data.Plural`. The leading `$` is required because we are inside a loop, and need to access variables from the outside scope. The link of the term is passed to the Hugo function `relURL` via a pipe `|` to make it relative, which is good practice because relative links are more portable (independent of the domain name).
Hugo automatically renders all taxonomy pages, and the path names are the plural forms of the taxonomies, e.g., https://xmin.yihui.org/categories/ and https://xmin.yihui.org/tags/. That is the meaning of `.Data.Plural`. The leading `$` is required because we are inside a loop, and need to access variables from the outside scope. The link of the term is passed to the Hugo function `relURL` via a pipe `|` to make it relative, which is good practice because relative links are more portable (independent of the domain name).

- The `partials/` directory is the place to put the HTML fragments to be reused by other templates via the `partial` function. We have four partial templates under this directory:

@@ -579,7 +579,7 @@ To understand `layouts/`, you must know some basics about HTML (see Section \@re

```js
[params]
footer = "&copy; [Yihui Xie](https://yihui.name) 2017"
footer = "&copy; [Yihui Xie](https://yihui.org) 2017"
```

There is a special template `404.html`, which Hugo uses to create the 404\index{404.html} page (when a page is not found, this page is displayed):
@@ -742,7 +742,7 @@ The XMin is actually a highly functional theme, but we understand that it may be
- **Support math expressions through MathJax.** Add the code below\index{MathJax} to `foot_custom.html`.

```html
<script src="//yihui.name/js/math-code.js"></script>
<script src="//yihui.org/js/math-code.js"></script>
<script async
src="//YOUR-CDN-LINK/MathJax.js?config=TeX-MML-AM_CHTML">
</script>
@@ -14,7 +14,7 @@ As we just mentioned, Netlify\index{Netlify} allows you to quickly publish a web

Basically, you have to host all source files of your website in a GIT repository.^[If the contents of your `blogdown` site are not in the root directory of your GIT repository, Netlify will not build.] You do not need to put the `public/` directory under version control^[You can add `public` to `.gitignore` to ignore it in GIT.] because it will be automatically generated. Currently, Netlify supports GIT repositories hosted on GitHub, GitLab, and BitBucket. With any of these accounts, you can log into Netlify from its homepage and follow the guide to create a new site from your GIT repository.

Netlify supports several static website generators, including Jekyll and Hugo. For a new site, you have to specify a command to build your website, as well as the path of the publish directory. Netlify also supports multiple versions of Hugo, so the build command can be the default `hugo`. The default version is 0.17, which is too old, and we recommend that you use at least version 0.20. To specify a Hugo version greater or equal to 0.20, you need to create an environment variable `HUGO_VERSION` on Netlify. See the [Netlify documentation](https://www.netlify.com/docs/continuous-deployment/) for more information. The publish directory should be `public` unless you have changed it in your `config.toml`. Figure \@ref(fig:netlify-settings) shows the settings of the website https://t.yihui.name. You do not have to follow the exact settings for your own website; in particular, you may need to change the value of the environment variable `HUGO_VERSION` to a recent version of Hugo.^[By the time when this book is published, the version 0.24.1 may be too old.]
Netlify supports several static website generators, including Jekyll and Hugo. For a new site, you have to specify a command to build your website, as well as the path of the publish directory. Netlify also supports multiple versions of Hugo, so the build command can be the default `hugo`. The default version is 0.17, which is too old, and we recommend that you use at least version 0.20. To specify a Hugo version greater or equal to 0.20, you need to create an environment variable `HUGO_VERSION` on Netlify. See the [Netlify documentation](https://www.netlify.com/docs/continuous-deployment/) for more information. The publish directory should be `public` unless you have changed it in your `config.toml`. Figure \@ref(fig:netlify-settings) shows the settings of the website https://t.yihui.org. You do not have to follow the exact settings for your own website; in particular, you may need to change the value of the environment variable `HUGO_VERSION` to a recent version of Hugo.^[By the time when this book is published, the version 0.24.1 may be too old.]

```{r netlify-settings, fig.cap='Example settings of a website deployed on Netlify.', echo=FALSE, fig.align='center', out.width='100%'}
knitr::include_graphics('images/netlify-settings.png')
@@ -144,7 +144,7 @@ There are a few more things to explain and emphasize in `.travis.yml`:

- The `cache` option specifies all R packages to be cached, so the next time it will be faster to build the site (R packages do not need to be reinstalled from source). The `bin/` directory in the home directory is also cached because Hugo is installed there, and the next time Hugo does not need to be reinstalled.

- For the `deploy` option, there is an environment variable named `GITHUB_TOKEN`, and I have specified its value to be a GitHub personal access token via the Travis settings of this repository, so that Travis will be able to write to my repository after the website is built. The option `on` specifies that the deployment will only occur when the `master` branch is built. The `local_dir` option is the publish directory, which should default to `public` in Hugo. By default, the website is pushed to the `gh-pages` branch of this repository. The `fqdn` option specifies the custom domain of the website. I have set a CNAME record (see Appendix \@ref(domain-name)) to point `travis-blogdown.yihui.name` to `yihui.github.io`, so that GitHub is able to serve this website through this domain (in fact, Travis will write a `CNAME` file containing the domain to the `gh-pages` branch).
- For the `deploy` option, there is an environment variable named `GITHUB_TOKEN`, and I have specified its value to be a GitHub personal access token via the Travis settings of this repository, so that Travis will be able to write to my repository after the website is built. The option `on` specifies that the deployment will only occur when the `master` branch is built. The `local_dir` option is the publish directory, which should default to `public` in Hugo. By default, the website is pushed to the `gh-pages` branch of this repository. The `fqdn` option specifies the custom domain of the website. I have set a CNAME record (see Appendix \@ref(domain-name)) to point `travis-blogdown.yihui.org` to `yihui.github.io`, so that GitHub is able to serve this website through this domain (in fact, Travis will write a `CNAME` file containing the domain to the `gh-pages` branch).

If you use the `username.github.io` repository on GitHub, the website must be pushed to its `master` branch instead of `gh-pages` (this is the only exception). I recommend that you separate the source repository and the output repository. For example, you may have a `website-source` repository with the same settings as the above `.travis.yml` except for two new options under `deploy`:

@@ -26,9 +26,9 @@ plot(fit)
The slope of the regression is `r knitr::inline_expr('b[2, 1]')`.
````

Such a document can be compiled using the function `rmarkdown::render()`, or equivalently, by clicking the `Knit` button in RStudio. Under the hood, an R Markdown document is first compiled to Markdown\index{Markdown} through **knitr** [@R-knitr], which executes all program code in the document. Then the Markdown output document is compiled to the final output document through Pandoc, such as an HTML page, a PDF document, a Word document, and so on. It is important to know this two-step process, otherwise you may not know which package documentation to look up when you have questions. Basically, for anything related to the (R) code chunks, consult the **knitr** documentation (https://yihui.name/knitr/); for anything related to Markdown, consult the Pandoc documentation (https://pandoc.org).
Such a document can be compiled using the function `rmarkdown::render()`, or equivalently, by clicking the `Knit` button in RStudio. Under the hood, an R Markdown document is first compiled to Markdown\index{Markdown} through **knitr** [@R-knitr], which executes all program code in the document. Then the Markdown output document is compiled to the final output document through Pandoc, such as an HTML page, a PDF document, a Word document, and so on. It is important to know this two-step process, otherwise you may not know which package documentation to look up when you have questions. Basically, for anything related to the (R) code chunks, consult the **knitr** documentation (https://yihui.org/knitr/); for anything related to Markdown, consult the Pandoc documentation (https://pandoc.org).

An R Markdown document typically consists of YAML\index{YAML} metadata (optional) and the document body. YAML metadata are written between a pair of `---` to set some attributes of the document, such as the title, author, and date, etc. In the document body, you can mix code chunks and narratives. A code block starts with a chunk header ```` ```{r} ```` and ends with ```` ``` ````. There are many possible chunk options that you can set in the chunk header to control the output, e.g., you can set the figure height to 4 inches using ```` ```{r fig.height=4} ````. For all possible chunk options, see https://yihui.name/knitr/options/.
An R Markdown document typically consists of YAML\index{YAML} metadata (optional) and the document body. YAML metadata are written between a pair of `---` to set some attributes of the document, such as the title, author, and date, etc. In the document body, you can mix code chunks and narratives. A code block starts with a chunk header ```` ```{r} ```` and ends with ```` ``` ````. There are many possible chunk options that you can set in the chunk header to control the output, e.g., you can set the figure height to 4 inches using ```` ```{r fig.height=4} ````. For all possible chunk options, see https://yihui.org/knitr/options/.

Pandoc supports a large variety of output document formats. For **blogdown**, the output format is set to HTML (`blogdown::html_page`), since a website typically consists of HTML pages. If you want other formats, please see Section \@ref(static-files). To create an R Markdown post for **blogdown**, it is recommended that you use the RStudio "New Post" (Figure \@ref(fig:new-post)) or the function `blogdown::new_post()`, instead of the RStudio menu `File -> New File -> R Markdown`.

0 comments on commit e9b81b2

Please sign in to comment.
You can’t perform that action at this time.