---
title: "Tools for README & Documentation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Tools for README & Documentation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| include = FALSE
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r}
#| label = "setup",
#| eval = FALSE
library(rpkgkit)
dir <- file.path(tempdir(), "example")
usethis::create_package(dir, open = FALSE)
usethis::local_project(dir)
usethis::use_readme_md(open = FALSE)
```

```{r}
#| label = "setup_bg",
#| include = FALSE,
#| echo = FALSE,
#| message = FALSE
library(rpkgkit)
```

# Manage README translations

`use_multilanguage_readme()` creates translation placeholders below
`inst/translations/` and prints Markdown badges that link to them.

```{r}
#| label = "use_multilanguage_readme",
#| eval = FALSE
use_multilanguage_readme(path = dir)
```

This will help you plan a good structure for multilingual README files.

# Badge management

## Insert badge strings into README

`badge_to_readme()` inserts one Markdown badge into the block delimited by
`<!-- badges: start -->` and `<!-- badges: end -->`. When both README files
exist, it updates `README.Rmd` rather than the generated `README.md`.

Usually you can adds a badge generated by `badger` + `badge_to_readme()`

```{r}
#| label = "badge_to_readme",
#| eval = FALSE
badger::badge_code_size() |>
  badge_to_readme()
```

A badge may also be supplied directly as a single Markdown string:

```{r}
#| label = "badge_to_readme_string",
#| eval = FALSE
badge_to_readme(
  "[![R-CMD-check](https://example.com/check.svg)](https://example.com)",
  path = dir
)
readLines("README.md") |> cli::cli_code()
```

If the exact badge is already present, the function leaves the file unchanged.

## Badge for AI-translated README files

`badge_translated_by_ai()` prints a badge and disclosure statement for
AI-translated README files.

```{r}
#| label = "badge_translated_by_ai"
badge_translated_by_ai("es")
```