# Home page

The main content of the home page (`index.html`) is generated from `pkgdown/index.md`, `index.md`, or `README.md`, in that order.
Most packages will use `README.md` because that's also displayed by GitHub and CRAN.
Use `index.md` if you want your package website to look different to your README, and use `pkgdown/index.md` if you don't want that file to live in your package root directory.

If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit the document to create the corresponding `.md`.
pkgdown does not do this for you because it only touches files in the `doc/` directory.

Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in `.github/` (e.g. `CODE_OF_CONDUCT.md`) are copied by `build_home()` to `docs/` and converted to HTML.

The home page also features a sidebar with information extracted from the package.
You can tweak it via the configuration file, to help make the home page an as informative as possible landing page.

## Images and figures

If you want to include images in your `README.md`, they must be stored somewhere in the package so that they can be displayed on the CRAN website.
The best place to put them is `man/figures`.
If you are generating figures with R Markdown, make sure you set up `fig.path` as followed:

``` r
knitr::opts_chunk$set(
  fig.path = "man/figures/"
)
```

This should usually go in a chunk with `include = FALSE`.

```` markdown
```{r chunk-name, include=FALSE}`r ''`
knitr::opts_chunk$set(
  fig.path = "man/figures/"
)
```
````

## Package logo

If you have a package logo, you can include it at the top of your README in a level-one heading:

``` markdown
# pkgdown <img src="man/figures/logo.png" align="right" />
```

[init_site()] will also automatically create a favicon set from your package logo.

## YAML config - home

To tweak the home page, you need a section of the configuration file called `home`.

### Page title and description

By default, the page title and description are extracted automatically from the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes off quoted words).
CRAN ensures that these fields don't contain phrases like "R package" because that's obvious on CRAN.
To make your package more findable on search engines, it's good practice to override the `title` and `description`, thinking about what people might search for:

``` yaml
home:
  title: An R package for pool-noodle discovery
  description: >
    Do you love R? Do you love pool-noodles? If so, you might enjoy
    using this package to automatically discover and add pool-noodles
    to your growing collection.
```

(Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)

### README header

READMEs usually start with an `<h1>` containing the package name.
If that feels duplicative with the package name in the navbar you can remove it with `strip_header: true`:

``` yaml
home:
  strip_header: true
```

## Dev badges

pkgdown identifies badges in three ways:

-   Any image-containing links between `<!-- badges: start -->` and `<!-- badges: end -->`, as e.g. created by `usethis::use_readme_md()` or `usethis::use_readme_rmd()`.
    There should always be an empty line after the `<!-- badges: end -->` line.
    If you divide badges into paragraphs, make sure to add an empty line before the `<!-- badges: end -->` line.

-   Any image-containing links within `<div id="badges"></div>`.

-   Within the first paragraph, if it only contains image-containing links.

Identified badges are **removed** from the _main content_.
They are shown or not in the _sidebar_ depending on the development mode and sidebar customization, see the sidebar section.
