### Install Rust and Dependencies

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Installs Rust using rustup and then installs essential build and linking dependencies using apt. Ensure you are in the correct directory before running these commands.

```bash
$ curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly
$ source $HOME/.cargo/env
# apt install build-essential git curl cmake gcc g++ pkg-config libmagic-dev libssl-dev zlib1g-dev postgresql lxc-utils
```

--------------------------------

### Start Docs.rs Web Server

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Starts the main web server for Docs.rs. It does not automatically run database migrations.

```sh
cargo run --bin docs_rs_web
```

--------------------------------

### Run Database Migrations and Web Server with Docker Compose

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Use these commands for pure Docker Compose setups to manage database migrations and start the web server.

```sh
just cli-db-migrate
just compose-up-web
```

--------------------------------

### Start the docs.rs web server

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Starts the web interface of docs.rs. This command is used to launch the local development server.

```sh
# This command will start web interface of docs.rs on http://localhost:3000
cargo run --bin docs_rs_webserver start-web-server
```

--------------------------------

### Install Rust and Dependencies

Source: https://github.com/rust-lang/docs.rs/wiki/Developing-without-docker-compose

Installs the nightly Rust toolchain and essential system dependencies for building docs.rs. It also sets up the PostgreSQL user and database required by the service.

```console
$ curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly
$ . $HOME/.cargo/env
# apt install build-essential git curl cmake gcc g++ pkg-config libmagic-dev libssl-dev zlib1g-dev postgresql
$ sudo -u postgres psql -c "CREATE USER cratesfyi WITH PASSWORD 'password';"
$ sudo -u postgres psql -c "CREATE DATABASE cratesfyi OWNER cratesfyi;"
```

--------------------------------

### Ruby Code Block with Options

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

A Ruby code block example with a `startline` option.

```ruby
def foo(x)
  return 3
end
```

--------------------------------

### Set up cratesfyi user and install Rust toolchain in container

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Creates a 'cratesfyi' user inside the container and installs the nightly Rust toolchain with all default targets for cross-compilation.

```bash
lxc-attach -n cratesfyi-container -- adduser --disabled-login --disabled-password --gecos "" cratesfyi
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add i686-apple-darwin'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add i686-pc-windows-msvc'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add i686-unknown-linux-gnu'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add x86_64-apple-darwin'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add x86_64-pc-windows-msvc'
```

--------------------------------

### LaTeX Command and Verbatim Examples

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Demonstrates how to use LaTeX commands and display verbatim text, including comments.

```latex
\command{}
```

```latex
`\command{}`
```

```latex
`foo % bar`
```

```latex
% ^ support.function.begin.latex
%        ^ variable.parameter.function.latex
The \emph{verbatim} environment sets everything in verbatim.
% <- meta.environment.verbatim.verbatim.latex
% ^ markup.raw.verbatim.latex
%         ^ - markup.italic.emph.latex
\command{}
% ^ - support.function.general.latex
% This is not a comment
% <- - comment.line.percentage.tex
```

--------------------------------

### Install Browser UI Test Package

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Installs the necessary `browser-ui-test` npm package for running GUI tests manually.

```sh
npm install browser-ui-test
```

--------------------------------

### Clone and Setup Docs.rs Project

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Initial steps to clone the repository, update submodules, configure environment variables, and prepare the necessary directories.

```sh
git clone https://github.com/rust-lang/docs.rs.git docs.rs
cd docs.rs
git submodule update --init
cp .env.sample .env
mkdir -p ignored/cratesfyi-prefix/crates.io-index
```

--------------------------------

### Cargo.toml Metadata Example

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/core/about/metadata.html

Example of the [package.metadata.docs.rs] table in Cargo.toml for customizing docs.rs builds. This configuration allows for setting specific flags for documentation generation.

```toml
[package]
name = "my-crate"
version = "0.1.0"

[package.metadata.docs.rs]
version = "1.60"
features = ["full"]
all-features = true
no-default-features = true

```

--------------------------------

### LaTeX List Environments

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Shows examples of common list environments in LaTeX: itemize, enumerate, description, and a custom list.

```latex
\begin{itemize}
\item first item

\end{itemize}
```

```latex
\begin{enumerate}
\item first item

\end{enumerate}
```

```latex
\begin{description}
\item[item] description of item

\end{description}
```

```latex
\begin{list}{(\arabic{listcounter})}{\usecounter{listcounter}}
\item first item

\end{list}
```

--------------------------------

### Run Docs.rs with Auto-Restart

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Starts the web server using `cargo-watch` for automatic restarts when code or templates change.

```sh
cargo watch -x "run --bin docs_rs_web"
```

--------------------------------

### Build and Run External Services

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Builds the docs.rs binary and starts the external services (database and S3) using Docker Compose.

```sh
SQLX_OFFLINE=1 cargo build
docker compose up --wait db s3
```

--------------------------------

### LaTeX URL and Path Commands

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Provides examples for creating hyperlinks and displaying file paths in LaTeX documents.

```latex
\url{https://www.sublimetext.com/}
```

```latex
\href{https://www.sublimetext.com/}
```

```latex
\path{$HOME/path/to/file}
```

--------------------------------

### Add a system package directly to Dockerfile

Source: https://github.com/rust-lang/docs.rs/wiki/Making-changes-to-the-build-environment

This is an example of how to add a system package directly to the Dockerfile for faster iteration during development. Remember to move this to `packages.txt` later.

```dockerfile
RUN apt-get install -y your_second_package
```

--------------------------------

### Hard Line Break Examples

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Demonstrates how to create hard line breaks using trailing spaces or a backslash.

```markdown
hard line break  

```

```markdown
hard line break\

```

```markdown
hard line break     

```

```markdown
### foo  

```

```markdown
### foo\

```

```markdown
`inline code with trailing spaces  
not a hard line break`
```

--------------------------------

### LaTeX Math Mode Examples

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Illustrates different ways to display mathematical equations in LaTeX, including inline, display, and equation environments.

```latex
$f(x) = x^2$
```

```latex
$$f(x) = x^2$$
```

```latex
\(f(x) = x^2\)
```

```latex
\[
  f(x) = x^2 \text{ $f$ is a function}
\]
```

```latex
f(x) = x^2
```

```latex
f(x) = x^2
```

```latex
$\iota$
```

```latex
$\Iota$
```

```latex
$\alpha _$
```

```latex
$\alpha_$
```

```latex
$f(x) = \} {} y$
```

--------------------------------

### Run GUI Tests Manually

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Starts the web server and then runs GUI tests manually using a Node.js script. Requires the `browser-ui-test` npm package.

```sh
node gui-tests/tester.js
```

--------------------------------

### LaTeX Table Alignment and Content

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Shows examples of table content alignment and structure in LaTeX.

```latex
a & b
```

```latex
*3>$}c<{$
```

```latex
 a & b & c
```

```latex
 1 & 2 & 3
```

--------------------------------

### Restart LXC network and manage container service

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Applies network changes, enables auto-start, and starts the 'cratesfyi-container' LXC service.

```bash
# systemctl restart lxc-net
# systemctl enable lxc@cratesfyi-container.service
# systemctl start lxc@cratesfyi-container.service
```

--------------------------------

### Inline Raw Text Example

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Demonstrates inline raw text with backticks, including nested backticks.

```markdown
`` foo ` bar  ``
```

```markdown
` `` `
```

```markdown
`foo   bar
  baz`
```

```markdown
hello world ````test````
```

```markdown
`foo `` bar`
```

--------------------------------

### Basic CSS in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

A concise example of embedding a simple CSS rule within Markdown.

```css
p{color:red;}
```

--------------------------------

### Run Registry Watcher with Docker Compose

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Start the registry watcher service using the `watcher` profile in Docker Compose to monitor for registry changes.

```sh
just compose-up-watcher
```

--------------------------------

### Install Sublime Text Packages on Linux

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/README.md

Clone the Packages repository and create a symbolic link to the desired syntax package in the Sublime Text 3 Packages directory.

```bash
git clone https://github.com/sublimehq/Packages.git
ln -s `pwd`/Packages/Python ~/.config/sublime-text-3/Packages/
```

--------------------------------

### Install Sublime Text Packages on Windows

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/README.md

Clone the Packages repository and create a directory junction to the desired syntax package in the Sublime Text 3 Packages directory using PowerShell.

```powershell
# Using PowerShell
PS> git clone https://github.com/sublimehq/Packages.git
PS> cmd /c mklink /J "$env:APPDATA/Sublime Text 3/Packages/Python" (convert-path ./Packages/Python)
```

--------------------------------

### Strikethrough Text Examples

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Illustrates the use of tildes for strikethrough text, including adjacent and nested cases.

```markdown
~Hi~ Hello, world!
```

```markdown
This ~text~~~~ is ~~~~curious~.
```

```markdown
This ~~has a
new paragraph~~.
```

--------------------------------

### Install Sublime Text Packages on OS X

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/README.md

Clone the Packages repository and create a symbolic link to the desired syntax package in the Sublime Text 3 Packages directory.

```bash
git clone https://github.com/sublimehq/Packages.git
ln -s `pwd`/Packages/Python ~/Library/Application\ Support/Sublime\ Text\ 3/Packages/
```

--------------------------------

### Listen for Storage Events in JavaScript

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/storage-change-detection.html

Attach an event listener to the window object to capture storage events. This example sends the key and new value to the parent window.

```javascript
onstorage = function(ev) { parent.postMessage({ storage: { key: ev.key, value: ev.newValue, } }) }
```

--------------------------------

### Get repository-specific build priority

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Retrieves the build priority override for a specific repository identified by 'owner/repo'.

```sh
cargo run --bin docs_rs_admin -- queue repository-priority get <owner/repo>
```

--------------------------------

### Get default build priority for a crate

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Retrieves the default build priority for a specific crate matching a Postgres pattern.

```sh
cargo run --bin docs_rs_admin -- queue default-priority get <CRATE_NAME>
```

--------------------------------

### Fenced Code Block Examples

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Shows different ways to use fenced code blocks, including empty blocks and blocks with language identifiers.

```markdown
~~~~ 
 ~~~~

```

```markdown
~~~~~test~

```

```markdown
~~~~~~
test
~~~~~~

```

```markdown
```test
  ```

```

--------------------------------

### Lock Crate Build Queue

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Run this command to create a lock file, preventing the crate-building process from starting new builds while the Rust compiler is updated.

```bash
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build lock"
```

--------------------------------

### Set up Prefix Directory and Index

Source: https://github.com/rust-lang/docs.rs/wiki/Developing-without-docker-compose

Creates the necessary directory structure for the docs.rs prefix and initializes the crates.io index for tracking crate releases.

```console
$ mkdir -p ignored/cratesfyi-prefix
$ cd ignored/cratesfyi-prefix
$ mkdir -vp documentations public_html sources
$ git clone https://github.com/rust-lang/crates.io-index && cd crates.io-index
$ git branch crates-index-diff_last-seen
```

--------------------------------

### Reset Last Seen Git Reference for Registry Watching

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Use this command to reset the starting point for watching registry changes to a specific Git reference.

```sh
just cli-queue-reset-last-seen-ref GIT_REF
```

--------------------------------

### Set default build priority for crates matching a pattern

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Sets a default build priority for crates matching a given Postgres pattern. For example, 'tokio-%' with a priority of -5.

```sh
cargo run --bin docs_rs_admin -- queue default-priority set 'tokio-%' -5
```

--------------------------------

### Initialize PostgreSQL Database for docs.rs

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

These commands set up the PostgreSQL database, create a user, and initialize the docs.rs database schema and essential files. It also includes adding a specific crate and updating search indexes and release activity.

```bash
sudo -u postgres sh -c "psql -c \"CREATE USER cratesfyi WITH PASSWORD 'password';\""
sudo -u postgres sh -c "psql -c \"CREATE DATABASE cratesfyi OWNER cratesfyi;\""
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- database init"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build add-essential-files"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build crate rand 0.5.5"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- database update-search-index"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- database update-release-activity"
```

--------------------------------

### Configure and Migrate Database

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Loads environment variables from .env file and sets up the database by running migrations.

```sh
. ./.env
# allow downloads from the s3 container to support the /crate/.../download endpoint
mcli policy set download docsrs/rust-docs-rs
# Setup the database you just created
cargo run --bin docs_rs_admin -- database migrate
```

--------------------------------

### PHP Code Block in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Example of embedding PHP code within a Markdown document, useful for server-side scripting examples.

```php
var_dump(expression);
```

--------------------------------

### XML Code Block in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Example of embedding XML code within a Markdown document, suitable for configuration or data structure examples.

```xml
<?xml version="1.0" ?>
<example>
    <foobar />
</example>
```

--------------------------------

### Set up required folders and clone crates.io index

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Creates necessary subdirectories within the prefix and clones the crates.io index repository. Run as the 'cratesfyi' user for correct ownership.

```bash
$ sudo -u cratesfyi mkdir -vp /cratesfyi-prefix/documentations /cratesfyi-prefix/public_html /cratesfyi-prefix/sources
$ sudo -u cratesfyi git clone https://github.com/rust-lang/crates.io-index.git /cratesfyi-prefix/crates.io-index
$ sudo -u cratesfyi git --git-dir=/cratesfyi-prefix/crates.io-index/.git branch crates-index-diff_last-seen
```

--------------------------------

### Indented Markdown Table

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Shows a Markdown table that is indented, starting after the initial column.

```markdown
 | table that doesn't start at column 0 |
  | ---- |
  | blah |
| ^^^^^^^^ meta.table
| ^ punctuation.separator.table-cell
```

--------------------------------

### Regex Code Block

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

A simple regular expression example enclosed in a code block.

```regex
(?x)
\s+
```

--------------------------------

### JavaScript Code Block Example

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

A basic JavaScript for loop within a fenced code block.

```javascript
for (var i = 0; i < 10; i++) {
    console.log(i);
}
```

--------------------------------

### Clone and Build docs.rs Project

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Clone the docs.rs repository as the cratesfyi user and build the release version of the cratesfyi binary. This prepares the application for execution.

```console
sudo -u cratesfyi git clone https://github.com/rust-lang-nursery/docs.rs.git ~cratesfyi/docs.rs
sudo su - cratesfyi -c 'cd ~/docs.rs && cargo build --release'
cp -v /home/cratesfyi/docs.rs/target/release/cratesfyi /var/lib/lxc/cratesfyi-container/rootfs/usr/local/bin
```

--------------------------------

### Create and set ownership for the prefix directory

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Initializes the directory structure required for docs.rs self-hosting and ensures the 'cratesfyi' user has appropriate permissions.

```bash
# mkdir /cratesfyi-prefix
# chown cratesfyi:cratesfyi /cratesfyi-prefix
```

--------------------------------

### Create 'cratesfyi' User and Configure Sudoers

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Creates a new unprivileged user 'cratesfyi' to run the docs.rs process and configures sudoers to allow this user to run 'lxc-attach' without a password. This user will own all necessary files.

```bash
# adduser --disabled-login --disabled-password --gecos ""
# echo 'cratesfyi  ALL=(ALL) NOPASSWD: /usr/bin/lxc-attach' > /etc/sudoers.d/cratesfyi
```

--------------------------------

### Initialize and Update Database

Source: https://github.com/rust-lang/docs.rs/wiki/Developing-without-docker-compose

Applies database migrations and updates the search index and release activity data. The initial update of the build environment can take a significant amount of time and download size.

```console
$ . ./env.sh
$ cargo run database migrate
$ cargo run database update-search-index
$ cargo run database update-release-activity
```

--------------------------------

### Markdown Thematic Breaks

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Provides examples of different syntaxes for creating thematic breaks (horizontal rules) in Markdown.

```markdown
- - - -
```

```markdown
* * * * *
```

```markdown
_ _ _ _ _ _ _
```

--------------------------------

### Clone docs.rs Repository and Build

Source: https://github.com/rust-lang/docs.rs/wiki/Developing-without-docker-compose

Clones the docs.rs repository and performs an initial build of the project. This step may take a significant amount of time due to the number of crates involved.

```console
$ git clone https://github.com/rust-lang/docs.rs && cd docs.rs
$ cargo build
```

--------------------------------

### Haskell Code Block in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Example of embedding Haskell code within a Markdown document using a preformatted block.

```haskell
import Text.HTML.TagSoup

main :: IO ()
main = print $ parseTags tags
```

--------------------------------

### Build the Docker image

Source: https://github.com/rust-lang/docs.rs/wiki/Making-changes-to-the-build-environment

Build the Docker image for the build environment. This process can take a significant amount of time.

```sh
docker build --tag build-env .
```

--------------------------------

### Command to build documentation targeting a local package

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

This command builds documentation by targeting a specific local package, typically after it has been packaged.

```bash
cargo run -- build crate --local /path/to/source/target/package/your_crate_name-version/

```

--------------------------------

### Build documentation for a packaged crate

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

After packaging a crate, use this command to build its documentation. The `-l` flag specifies the local path to the packaged crate.

```bash
cargo run -- build crate -l path/to/docs_rs_workspace_package/target/package/my_lib-0.1.0
```

--------------------------------

### SQL Code Block in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Demonstrates embedding SQL code within a Markdown document, useful for database query examples.

```sql
SELECT TOP 10 *
FROM TableName
```

--------------------------------

### Python Code Block in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Illustrates embedding Python code within a Markdown document, useful for code examples and tutorials.

```python
def function():
    pass
unclosed_paren = (
```

--------------------------------

### Configure LXC network for NAT

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Sample configuration for `/etc/default/lxc-net` to enable NAT networking for the LXC container.

```bash
USE_LXC_BRIDGE="true"
LXC_BRIDGE="lxcbr0"
LXC_ADDR="10.0.3.1"
LXC_NETMASK="255.255.255.0"
LXC_NETWORK="10.0.3.0/24"
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"
LXC_DHCP_MAX="253"
LXC_DHCP_CONFILE=""
LXC_DOMAIN=""
```

--------------------------------

### CSS Code Block in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Shows how to include CSS code snippets within Markdown, typically for styling examples or documentation.

```css
h1 {color:red;}

p {color:blue;}
```

--------------------------------

### Build a local package

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Builds a local package from a specified source path and adds it to the database. The package must exist on the local filesystem; Git URLs are not supported. This command can often be applied directly to a crate root.

```sh
# Builds a local package you have at <SOURCE> and adds it to the database.
# The package does not have to be on crates.io.
# The package must be on the local filesystem, git urls are not allowed.
# Usually this command can be applied directly to a crate root
# In certain scenarios it might be necessary to first package the respective
# crate by using the `cargo package` command.
# See also /docs/build-workspaces.md
cargo run --bin docs_rs_builder -- build crate --local /path/to/source
```

--------------------------------

### LaTeX Embedded Code Snippets (Minted)

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Examples of embedding code snippets using the minted package with different language specifiers.

```latex
\mint`pythonimport this
```

```python
import this
```

```latex
pythonprint(x ** 2)
```

```python
print(x ** 2)
```

```latex
python+print(x ** 2)+
```

```python
+print(x ** 2)+
```

--------------------------------

### Connect to the database using psql

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Connects to the database using the psql command-line client. This is useful for manually exploring or editing the database contents.

```sh
. ./.env
psql $DOCSRS_DATABASE_URL
```

--------------------------------

### LaTeX File Inclusion Commands

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Demonstrates commands for including and managing external LaTeX files.

```latex
\include{path/to/file}
```

```latex
\includeonly{path/to/file.tex}
```

```latex
\input{path/to/file.tex}
```

```latex
\includecommand{...}
```

```latex
\inputminted{py}{path/to/file.py}
```

--------------------------------

### Update and upgrade packages inside LXC container

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Updates the package list and upgrades existing packages within the 'cratesfyi-container'. Installs essential build tools.

```bash
# lxc-attach -n cratesfyi-container -- apt update
# lxc-attach -n cratesfyi-container -- apt upgrade
# lxc-attach -n cratesfyi-container -- apt install curl ca-certificates binutils gcc libc6-dev libmagic1 pkg-config build-essential
```

--------------------------------

### Create LXC container for documentation builds

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Creates an LXC container named 'cratesfyi-container' using Ubuntu Bionic. Ensure the container OS matches the host OS for simpler deployment.

```bash
# LANG=C lxc-create -n cratesfyi-container -P /cratesfyi-prefix -t download -- --dist ubuntu --release bionic --arch amd64
# ln -s /cratesfyi-prefix/cratesfyi-container /var/lib/lxc
# chmod 755 /cratesfyi-prefix/cratesfyi-container
# chmod 755 /var/lib/lxc
```

--------------------------------

### Build all crates on crates.io

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Builds every crate on crates.io and adds them to the database. Be aware that this process can take a significant amount of time.

```sh
# Builds every crate on crates.io and adds them into database
# (beware: this may take months to finish)
cargo run --bin docs_rs_builder -- build world
```

--------------------------------

### CDATA Section in Markdown

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Example of embedding a CDATA section within Markdown, often used to include blocks of text that should be treated as raw character data.

```javascript
function matchwo(a,b)
{
  if (a < b && a < 0) then {
    return 1;

  } else {

    return 0;
  }
}
```

--------------------------------

### LaTeX Text Formatting Commands

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Demonstrates basic text formatting commands in LaTeX for emphasis and style.

```latex
\emph{text}
```

```latex
\textbf{text}
```

```latex
\textit{text}
```

```latex
\texttt{text}
```

```latex
\textsl{text}
```

```latex
\textbf{\textit{text}}
```

```latex
\textit{\textbf{text}}
```

```latex
\underline{text}
```

--------------------------------

### Build a specific crate version

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Builds a specified crate and version, adding it to the database. This is the primary command for building and indexing documentation.

```sh
# Builds <CRATE_NAME> <CRATE_VERSION> and adds it into database
# This is the main command to build and add a documentation into docs.rs.
# For example, `docker compose run --rm builder-a build crate regex 1.1.6`
cargo run --bin docs_rs_builder -- build crate <CRATE_NAME> <CRATE_VERSION>
```

--------------------------------

### Import Release from Docs.rs

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

An alternative to building a crate locally, this command imports a release directly from docs.rs.

```sh
cargo run -p docs_rs_import_release -- regex latest
```

--------------------------------

### Build command that fails with workspace version

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

This command demonstrates the build process that fails when `version.workspace = true` is present and the crate is not pre-packaged.

```bash
cargo run -- build crate -l path/to/docs_rs_workspace_package/my_lib
```

--------------------------------

### Clone the crates-build-env repository

Source: https://github.com/rust-lang/docs.rs/wiki/Making-changes-to-the-build-environment

Use this command to clone the necessary repository to your local machine.

```console
git clone https://github.com/rust-lang/crates-build-env && cd crates-build-env
```

--------------------------------

### Initial Cargo.toml for workspace

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

This is the root Cargo.toml file for a workspace, defining members and package information.

```toml
[workspace]
members = [
        "my_lib",
]

[workspace.package]
version = "0.1.0"

```

--------------------------------

### LaTeX Embedded Code Highlighting (lstlisting)

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Demonstrates how to embed and highlight source code using the lstlisting environment, supporting multiple languages.

```latex
% python
def my_function():
    pass
% <- meta.environment.verbatim.lstlisting.latex
% <- meta.environment.embedded.python.latex
% <- source.python.embedded
%   ^ keyword.control.flow.pass.python
```

```python
def my_function():
    pass
```

```latex
%python
def my_function():
    pass
% <- meta.environment.verbatim.lstlisting.latex
% <- meta.environment.embedded.python.latex
% <- source.python.embedded
%   ^ keyword.control.flow.pass.python
```

```python
def my_function():
    pass
```

```latex
%java
class MyClass() {
% <- meta.environment.verbatim.lstlisting.latex
% <- meta.environment.embedded.java.latex
% <- source.java.embedded
% ^ storage.type.java
}
```

```java
class MyClass() {
}
```

--------------------------------

### Configure S3 Credentials and Endpoint

Source: https://github.com/rust-lang/docs.rs/wiki/Migrating-files-from-local-database-to-an-S3-compliant-provider

Set these environment variables in your docs.rs configuration file to point to your S3-compliant provider and configure access.

```text
AWS_ACCESS_KEY_ID=<access key>
AWS_SECRET_ACCESS_KEY=<access secret>
S3_ENDPOINT=<endpoint url>
```

--------------------------------

### Error message for failed build

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

This is the error message received when attempting to build documentation for a workspace crate with `version.workspace = true` without pre-packaging.

```bash
Error: Building documentation failed

Caused by:
    Building documentation failed

Caused by:
    invalid Cargo.toml syntax

```

--------------------------------

### Run All Tests

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Executes all unit and integration tests for the Docs.rs project.

```sh
cargo test
```

--------------------------------

### Configure systemd Service for Cratesfyi Daemon

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

This systemd service file defines how to run the Cratesfyi daemon, which collects crate information, orchestrates builds, and serves the website. Ensure the environment file and paths are correctly set.

```systemd
[Unit]
Description=Cratesfyi daemon
After=network.target postgresql.service

[Service]
User=cratesfyi
Group=cratesfyi
Type=forking
PIDFile=/cratesfyi-prefix/cratesfyi.pid
EnvironmentFile=/home/cratesfyi/.cratesfyi.env
ExecStart=/home/cratesfyi/docs.rs/target/release/cratesfyi daemon
WorkingDirectory=/home/cratesfyi/docs.rs

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Configuring Docs.rs Build Arguments (TOML)

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/core/about/builds.html

Add package metadata to `Cargo.toml` to customize how Docs.rs builds your crate. This can include setting compiler arguments for conditional compilation or managing cargo features.

```toml
[package.metadata.docs.rs]
rustc-args = ["--cfg", "my_cfg"]
```

--------------------------------

### Build a Specific Crate

Source: https://github.com/rust-lang/docs.rs/wiki/Developing-without-docker-compose

Builds a specific crate (e.g., 'rand' version 0.5.5) using the configured environment. This is useful for testing individual crate builds.

```console
# This will take between 5 and 30 minutes on the first run, depending on your internet speed.
# It downloads the rustops/crates-build-env crates which is over 4 GB.
# It does not currently display a progress bar, this is https://github.com/rust-lang/rustwide/issues/9
# As a workaround, you can run `docker pull rustops/crates-build-env` in a separate terminal.
$ cargo run build crate rand 0.5.5
```

--------------------------------

### Initialize Release Activity Chart

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/releases/activity.html

This JavaScript code initializes a line chart to visualize release activity. It requires a canvas element with the ID 'releases-activity-chart' and data for dates, release counts, and build failures. Chart.platform.disableCSSInjection is set to true to manage CSS injection separately.

```javascript
// We're including the CSS file manually to avoid issues with the CSP.
Chart.platform.disableCSSInjection = true;
var ctx = document.getElementById("releases-activity-chart").getContext("2d");
new Chart(ctx, {
  type: "line",
  data: {
    labels: {{ dates|fmt("{:?}")|safe }},
    datasets: [
      {
        label: "Releases",
        borderColor: "#4d76ae",
        backgroundColor: "#4d76ae",
        fill: false,
        data: {{ counts|fmt("{:?}")|safe }},
      },
      {
        label: "Build Failures",
        borderColor: "#434348",
        backgroundColor: "#434348",
        fill: false,
        data: {{ failures|fmt("{:?}")|safe }},
      },
    ],
  },
  options: {
    animation: false,
    tooltips: {
      mode: "index",
      intersect: false,
    },
    scales: {
      yAxes: [
        {
          ticks: {
            beginAtZero: true,
          },
        }
      ],
    },
  },
});
```

--------------------------------

### Symlink Rust toolchain from container to host

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Creates symbolic links on the host for the 'cratesfyi' user's Rust configuration directories, pointing to the versions inside the LXC container. This avoids managing a separate toolchain on the host.

```bash
for directory in .cargo .rustup .multirust; do  [[ -h /home/cratesfyi/$directory ]] || sudo -u cratesfyi ln -vs /var/lib/lxc/cratesfyi-container/rootfs/home/cratesfyi/$directory /home/cratesfyi/; done
```

--------------------------------

### Run GUI Tests

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Executes graphical user interface tests using the `just run-gui-tests` command. Requires the browser-ui-test framework.

```sh
just run-gui-tests
```

--------------------------------

### LaTeX Minted Package for Code Highlighting

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Demonstrates code highlighting using the minted package, which leverages the Pygments library.

```latex
% python
def my_function():
    pass
% <- meta.environment.verbatim.minted.latex
% <- meta.environment.embedded.python.latex
% <- source.python.embedded
%   ^ keyword.control.flow.pass.python
```

```python
def my_function():
    pass
```

--------------------------------

### LaTeX Footnote Commands

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Illustrates different ways to create footnotes in LaTeX, including standard footnotes, footnotes with specific reference marks, and creating footnotes without marks.

```latex
\footnote{This is a basic footnote}
```

```latex
\footnote [ 5 ] {This is a footnote with a specific reference mark}
```

```latex
\footnotetext{Footnote text without creating a mark}
```

```latex
\footnotemark
```

```latex
\footnotemark  [ 1   ]
```

--------------------------------

### Build docs.rs with lock

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Execute the build command for docs.rs with the 'lock' argument to prevent the daemon from building new crates. This ensures a stable environment for updates. Alternatively, `systemctl stop cratesfyi` can be used if downtime is acceptable.

```console
$ sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build lock"
```

--------------------------------

### Create Environment Script for Server

Source: https://github.com/rust-lang/docs.rs/wiki/Developing-without-docker-compose

Generates a shell script to set essential environment variables for the docs.rs server, including the prefix directory, database URL, and logging level.

```sh
$ cd ..
$ echo '
export CRATESFYI_PREFIX=.
# or add an appropriate username/password as necessary
export CRATESFYI_DATABASE_URL=postgresql://cratesfyi:password@localhost
export CRATESFYI_GITHUB_USERNAME=
export CRATESFYI_GITHUB_ACCESSTOKEN=
export RUST_LOG=cratesfyi,rustwide=info
' > env.sh
```

--------------------------------

### Replace and restart docs.rs service

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Copy the newly built cratesfyi executable to its designated location and restart the cratesfyi service to apply the updates. This ensures the running service uses the latest build.

```console
# cp -v /home/cratesfyi/docs.rs/target/release/cratesfyi /var/lib/lxc/cratesfyi-container/rootfs/usr/local/bin
# systemctl restart cratesfyi
```

--------------------------------

### Test the Docker image with a crate

Source: https://github.com/rust-lang/docs.rs/wiki/Making-changes-to-the-build-environment

Use the built Docker image to build a specific crate. Ensure the crate path is absolute. This command runs the build process within a Docker container, mounting the crate directory.

```sh
cd /path/to/docs.rs
docker-compose build
# NOTE: this must be an absolute path, not a relative path
# On platforms with coreutils, you can instead use `$(realpath ../relative/path)`
YOUR_CRATE=/path/to/your/crate
# avoid docker-compose creating the volume if it doesn't exist
if [ -e "$YOUR_CRATE" ]; then
  docker-compose run -e DOCS_RS_LOCAL_DOCKER_IMAGE=build-env \
                     -v "$YOUR_CRATE":/opt/rustwide/workdir \
    web build crate --local /opt/rustwide/workdir
else
  echo "$YOUR_CRATE does not exist";
fi
```

--------------------------------

### Create Menu Link with Solid Icon Macro

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/macros.html

Defines a macro for creating markdown-formatted links that include a solid icon. It takes href, text, icon, and an optional target.

```html
{% macro menu_link_with_icon_solid(href, text, icon, target="") -%}
*   {#- -#}
    [{{- icon.render_solid(false, false, "") }} {{ text -}}]({{ href }}) {#- -#}
{%- endmacro menu_link_with_icon_solid %}
```

--------------------------------

### Migrate Files and Restart Service

Source: https://github.com/rust-lang/docs.rs/wiki/Migrating-files-from-local-database-to-an-S3-compliant-provider

Use the cratesfyi CLI to lock the build queue, migrate files from the database to S3, and restart the docs.rs service. This process ensures no new files are added during migration.

```sh
cratesfyi build lock
# edit the environment file with the above variables if you haven't already
cratesfyi database move-to-s3 # this will take a while, depending on the size of your database
sudo systemctl restart cratesfyi # or however you manage your docs.rs service
# verify that files are loading from S3/Minio/etc
cratesfyi build unlock
```

--------------------------------

### Configure container network interface

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Adds necessary lines to the container's configuration file to use the 'lxcbr0' bridge for networking.

```bash
lxc.net.0.type = veth
lxc.net.0.link = lxcbr0
```

--------------------------------

### LaTeX Document Structure Commands

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Illustrates commands for defining document structure elements like parts, chapters, sections, and subsections.

```latex
\part{name}
```

```latex
\chapter{name}
```

```latex
\section{name}
```

```latex
\subsection{name}
```

```latex
\subsubsection{name}
```

```latex
\paragraph{name}
```

```latex
\subparagraph{name}
```

--------------------------------

### LaTeX Special Characters and Escaping

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Illustrates how to use and escape special characters within LaTeX.

```latex
|x|@See: >$}l<{$|
```

--------------------------------

### Bash Script with Continuation

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Shows a basic bash script with a comment and a command using line continuation.

```bash
# test
echo hello, \
echo This is a smiley :-\)
(I have to escape the parentheses, though!)
```

--------------------------------

### List repository-specific build priorities

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Inspects or manages build priority overrides for specific repositories. These overrides use the format 'owner/repo'.

```sh
# Inspect or manage repository-specific build priority overrides using repositories.name.
cargo run --bin docs_rs_admin -- queue repository-priority list
```

--------------------------------

### List default build priorities for crates

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Inspects or manages the default build priorities for crates that match a Postgres pattern. This allows for setting custom priorities for groups of crates.

```sh
# Inspect or manage default priorities for crates matching a Postgres pattern.
cargo run --bin docs_rs_admin -- queue default-priority list
```

--------------------------------

### take

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/lib/docs_rs_storage/tests/regex/body.html

Creates an iterator that yields only the first `n` elements.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields only the first `n` elements.

### Method
Iterator method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **n** (usize) - Required - The maximum number of elements to yield.
```

--------------------------------

### Create Crate Limits Table Macro

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/macros.html

Defines a macro for generating a formatted table that displays a crate's resource limits. It takes a `Limits` struct as input.

```html
{# Creates a formatted table showing the resource limits of a crate * `limits` A non-null `Limits` struct #} {% macro crate_limits(limits) %}

Available RAM

{{ limits.memory|filesizeformat }}

Maximum rustdoc execution time

{{ limits.timeout|format_duration }}

Maximum size of a build log

{{ limits.max_log_size|filesizeformat }}

Network access

{%- if limits.networking -%} allowed {%- else -%} blocked {%- endif -%}

Maximum number of build targets

{{ limits.targets }}

{%- endmacro crate_limits %}
```

--------------------------------

### Package a specific crate in a workspace

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

Use this command to package a specific crate within a workspace. This is necessary when `version.workspace = true` is used and rustdoc needs a fully specified package.

```bash
cargo package -p my_lib
```

--------------------------------

### Create Menu Link Macro

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/macros.html

Defines a macro for creating markdown-formatted links for menu items. It accepts href, text, and an optional target.

```html
{# Creates a list entry * `href` A string used as the tab's link * `text` A string used as the tab's text * `target` An optional target * `extra_classes` Optional extra css classes #} {% macro menu_link(href, text, target, icon="") -%}
*   {#- -#}
    [{{ text }}]({{ href }}) {#- -#}
{%- endmacro menu_link %}
```

--------------------------------

### Create Menu Link with Brand Icon Macro

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/macros.html

Defines a macro for creating markdown-formatted links that include a brand icon. It requires href, text, and an icon object.

```html
{% macro menu_link_with_icon_brand(href, text, icon) -%}
*   {#- -#}
    [{{- icon.render_brands(false, false, "") }} {{ text -}}]({{ href }}) {#- -#}
{%- endmacro menu_link_with_icon_brand %}
```

--------------------------------

### Tilde Escaping in Path

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/Markdown/syntax_test_markdown.md

Demonstrates escaping a tilde character in a file path.

```shell
~/.bashrc
```

--------------------------------

### Update Toolchain and Build Crate

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Updates the Rust toolchain to the latest nightly and builds a sample crate (regex) to verify the build environment.

```sh
# Update the currently used toolchain to the latest nightly
# This also sets up the docs.rs build environment.
# This will take a while the first time but will be cached afterwards.
cargo run --bin docs_rs_builder -- build update-toolchain
# Build a sample crate to make sure it works
cargo run --bin docs_rs_builder -- build crate regex 1.3.1
```

--------------------------------

### LaTeX Inline Code Highlighting (lstinline)

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/assets/syntaxes/Packages/LaTeX/syntax_test_latex.tex

Shows how to display inline code snippets using the lstinline command.

```latex
`var x = 15;}`
% ^^^^^^^^^^^^^^^^^^^^^ meta.environment.verbatim.lstinline.latex
%         ^^^^^^^^^^^^^ meta.group.brace.latex
%         ^ punctuation.definition.group.brace.begin.latex
%          ^^^^^^^^^^^ markup.raw.verb.latex
%                     ^ punctuation.definition.group.brace.end.latex
%                      ^ - meta.environment.verbatim.lstinline.latex
```

```latex
\lstinline|var x = 15;|
```

--------------------------------

### Load Environment Variables and Update PATH

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Load environment variables from the .cratesfyi.env file and append necessary directories to the system's PATH. This ensures the system can find the cargo and docs.rs binaries.

```shell
export $(cat $HOME/.cratesfyi.env | xargs -d '\n')
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$PATH:$HOME/docs.rs/target/release"
```

--------------------------------

### Configure cratesfyi Environment Variables

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

Set essential environment variables for the cratesfyi user in its home directory. This includes paths, database URLs, and optional GitHub credentials.

```shell
CRATESFYI_PREFIX=/cratesfyi-prefix
CRATESFYI_DATABASE_URL=postgresql://cratesfyi:password@localhost
CRATESFYI_CONTAINER_NAME=cratesfyi-container
CRATESFYI_GITHUB_USERNAME=
CRATESFYI_GITHUB_ACCESSTOKEN=
RUST_LOG=cratesfyi
```

--------------------------------

### Add Essential Files After Update

Source: https://github.com/rust-lang/docs.rs/wiki/Self-hosting-outside-the-Vagrant-VM

After updating the Rust compiler, run this command to add necessary Rustdoc static files to the database. This is part of the compiler update procedure.

```bash
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build add-essential-files"
```

--------------------------------

### Queue a specific crate release for building

Source: https://github.com/rust-lang/docs.rs/blob/main/README.md

Queues a specific crate release for building. An optional priority can be set, with lower numbers indicating higher priority. The default priority is 5.

```sh
# Queue a specific crate release for building.
# The optional `--priority` defaults to 5. Lower numbers run first.
cargo run --bin docs_rs_admin -- queue add <CRATE_NAME> <CRATE_VERSION>
```

--------------------------------

### Displaying File Content with Line Numbers

Source: https://github.com/rust-lang/docs.rs/blob/main/crates/bin/docs_rs_web/templates/crate/source.html

This snippet shows how to display the content of a file with line numbers. It uses a loop to generate line numbers and then renders the file content with syntax highlighting.

```html
{%- for line in 1..=file_content.lines().count() -%}
                                {{line}}
                            {%~ endfor -%}
                        

{{- file_content|highlight(file_name) -}}
```

--------------------------------

### General cargo package command

Source: https://github.com/rust-lang/docs.rs/blob/main/docs/build-workspaces.md

This command packages a crate, which is a prerequisite for building documentation when workspace inheritance is used.

```bash
cargo package

```