Skip to content

Commit

Permalink
docs: options one-pager (#9533)
Browse files Browse the repository at this point in the history 
### Description

A cross-reference for the various ways you can tune behavior of `turbo`.

### Testing Instructions

👀
  • Loading branch information
@anthonyshew
anthonyshew authored Dec 5, 2024
1 parent 2f0a75b commit 04b284a
Show file tree
Hide file tree
Showing 7 changed files with 7,664 additions and 5,582 deletions.
2 changes: 2 additions & 0 deletions docs/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
"dependencies": {
"github-slugger": "2.0.0",
"gray-matter": "4.0.3",
"hast-util-select": "^6.0.3",
"rehype-parse": "^9.0.1",
"rehype-raw": "7.0.0",
"remark-parse": "11.0.0",
"remark-rehype": "11.1.1",
Expand Down
3 changes: 0 additions & 3 deletions docs/repo-docs/reference/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -534,7 +534,6 @@ Sets a timeout for remote cache operations.
Value is given in seconds and only whole values are accepted.
If `0` is passed, then there is no timeout for any cache operations.

<InVersion version="2.3.2">
### `uploadTimeout`

Default: `60`
Expand All @@ -543,8 +542,6 @@ Sets a timeout for remote cache uploads.
Value is given in seconds and only whole values are accepted.
If `0` is passed, then there is no timeout for any remote cache uploads.

</InVersion>

### `apiUrl`

Default: `"https://vercel.com"`
Expand Down
1 change: 1 addition & 0 deletions docs/repo-docs/reference/meta.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"package-configurations",
"system-environment-variables",
"globs",
"options-one-pager",
"---Commands---",
"run",
"watch",
Expand Down
118 changes: 118 additions & 0 deletions docs/repo-docs/reference/options-one-pager.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
---
title: Options one-pager
description: Flags, configurations, and System Environment Variables for Turborepo
---

There are three ways to manage the behavior of a `turbo` invocation:

- [Configuration in `turbo.json`](/repo/docs/reference/configuration)
- [System Environment Variables](/repo/docs/reference/system-environment-variables)
- [Flags passed to the CLI invocation](/repo/docs/reference/run)

The three strategies listed above are in order of precedence. Where a flag value is provided, for the same System Environment Variable or `turbo.json` configuration, the value for the flag will be used. Because of this, we recommend using:

- `turbo.json` configuration for defaults
- System Environment Variables for per-environment overrides
- Flags for per-invocation overrides

## Options table

### Caching

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Force tasks to run | [`--force`](/repo/docs/reference/run#--force) | [`TURBO_FORCE`](/repo/docs/reference/system-environment-variables#turbo_force) | [`cache`](/repo/docs/reference/configuration#cache) |
| Remote Cache timeout | [`--remote-cache-timeout`](/repo/docs/reference/configuration#timeout) | [`TURBO_REMOTE_CACHE_TIMEOUT`](/repo/docs/reference/system-environment-variables#turbo_remote_cache_timeout) | [`remoteCache.timeout`](/repo/docs/reference/configuration#timeout) |
| Remote Cache upload timeout | - | [`TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT`](/repo/docs/reference/system-environment-variables#turbo_remote_cache_upload_timeout) | [`remoteCache.uploadTimeout`](/repo/docs/reference/configuration#uploadtimeout) |
| Cache signature key | - | [`TURBO_REMOTE_CACHE_SIGNATURE_KEY`](/repo/docs/reference/system-environment-variables#turbo_remote_cache_signature_key) | [`signature`](/repo/docs/reference/configuration#signature) |
| Preflight request | [`--preflight`](/repo/docs/reference/run#--preflight) | [`TURBO_PREFLIGHT`](/repo/docs/reference/system-environment-variables#turbo_preflight) | [`remoteCache.preflight`](/repo/docs/reference/configuration#preflight) |
| Remote Cache base URL | - | [`TURBO_API`](/repo/docs/reference/system-environment-variables#turbo_api) | [`remoteCache.apiUrl`](/repo/docs/reference/configuration#remote-caching) |
| Cache sources | [`--cache`](/repo/docs/reference/run#--cache-options) | [`TURBO_CACHE`](/repo/docs/reference/system-environment-variables#turbo_cache) | - |
| Local cache directory | [`--cache-dir`](/repo/docs/reference/run#--cache-dir-path) | [`TURBO_CACHE_DIR`](/repo/docs/reference/system-environment-variables#turbo_cache_dir) | [`cacheDir`](/repo/docs/reference/configuration#cachedir) |

</div>

### Messages

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| ------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------ | ---------- |
| Disable version print | - | [`TURBO_PRINT_VERSION_DISABLED`](/repo/docs/reference/system-environment-variables#turbo_print_version_disabled) | - |
| Disable telemetry message | - | [`TURBO_TELEMETRY_MESSAGE_DISABLED`](/repo/docs/reference/system-environment-variables#turbo_telemetry_message_disabled) | - |
| Disable global `turbo` warning | - | [`TURBO_GLOBAL_WARNING_DISABLED`](/repo/docs/reference/system-environment-variables#turbo_global_warning_disabled) | - |
| No update notifier | - | [`TURBO_NO_UPDATE_NOTIFIER`](/repo/docs/reference/system-environment-variables#turbo_no_update_notifier) | - |

</div>

### Task running and logs

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Terminal UI | [`--ui`](/repo/docs/reference/run#--ui) | [`TURBO_UI`](/repo/docs/reference/system-environment-variables#turbo_ui) | [`ui`](/repo/docs/reference/configuration#ui) |
| Run affected tasks | [`--affected`](/repo/docs/reference/run#--affected) | - | - |
| Disable package manager check | [`--dangerously-disable-package-manager-check`](/repo/docs/reference/run#--dangerously-disable-package-manager-check) | [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](/repo/docs/reference/system-environment-variables#turbo_dangerously_disable_package_manager_check) | [`dangerouslyDisablePackageManagerCheck`](/repo/docs/reference/configuration#dangerouslydisablepackagemanagercheck) |
| Affected base ref | - | [`TURBO_SCM_BASE`](/repo/docs/reference/system-environment-variables#turbo_scm_base) | - |
| Affected head ref | - | [`TURBO_SCM_HEAD`](/repo/docs/reference/system-environment-variables#turbo_scm_head) | - |
| Only run directly specified tasks | [`--only`](/repo/docs/reference/run#--only) | - | - |
| Task concurrency | [`--concurrency`](/repo/docs/reference/run#--concurrency-number--percentage) | - | - |
| Task log order | [`--log-order`](/repo/docs/reference/run#--log-order-option) | [`TURBO_LOG_ORDER`](/repo/docs/reference/system-environment-variables#turbo_log_order) | - |
| Current working directory | [`--cwd`](/repo/docs/reference/run#--cwd-path) | - | - |
| Streamed logs prefix | [`--log-prefix`](/repo/docs/reference/run#--log-prefix-option) | - | - |
| Task logs output level | [`--output-logs-option`](/repo/docs/reference/run#--output-logs-option) | - | [`outputLogs`](/repo/docs/reference/configuration#outputlogs) |
| Global inputs | [`--global-deps`](/repo/docs/reference/run#--global-deps-file-glob) | - | [`globalDependencies`](/repo/docs/reference/configuration#globaldependencies) |

</div>

### Environment variables

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| ----------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| Environment variable mode | [`--env-mode`](/repo/docs/reference/run#--env-mode-option) | - | [`envMode`](/repo/docs/reference/configuration#envmode) |
| Vendor environment variables | - | [`TURBO_CI_VENDOR_ENV_KEY`](/repo/docs/reference/system-environment-variables#turbo_ci_vendor_env_key) | - |
| Framework variable exceptions | [`--framework-inference`](/repo/docs/reference/run#--framework-inference) | - | - |

</div>

### Debugging outputs

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| ------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| Run Summaries | [`--summarize`](/repo/docs/reference/run#--summarize) | [`TURBO_RUN_SUMMARY`](/repo/docs/reference/system-environment-variables#turbo_run_summary) | - |
| Graph visualization | [`--graph`](/repo/docs/reference/run#--graph-file-type) | - | - |
| Dry run | [`--dry`](/repo/docs/reference/run#--dry----dry-run) | - | - |

</div>

### Authentication

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| --------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Login URL | - | [`TURBO_LOGIN`](/repo/docs/reference/system-environment-variables#turbo_login) | [`remoteCache.loginUrl`](/repo/docs/reference/configuration#loginurl) |
| Team name (for multi-team Remote Cache) | [`--team`](/repo/docs/reference/run#--team) | [`TURBO_TEAM`](/repo/docs/reference/system-environment-variables#turbo_team) | - |
| Team ID (for multi-team Remote Cache) | - | [`TURBO_TEAMID`](/repo/docs/reference/system-environment-variables#turbo_teamid) | - |
| Authentication token | [`--token`](/repo/docs/reference/run#--token) | [`TURBO_TOKEN`](/repo/docs/reference/system-environment-variables#turbo_token) | - |

</div>

### Other

<div className="options-cheat-sheet-table">

| Behavior | Flags | Environment Variables | turbo.json |
| ---------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Binary path | - | [`TURBO_BINARY_PATH`](/repo/docs/reference/system-environment-variables#turbo_binary_path) | - |
| Download local `turbo` | - | [`TURBO_DOWNLOAD_LOCAL_ENABLED`](/repo/docs/reference/system-environment-variables#turbo_download_local_enabled) | - |
| Daemon | [`--daemon` / `--no-daemon`](/repo/docs/reference/run#--daemon-and---no-daemon) | - | [`daemon`](/repo/docs/reference/configuration#daemon) |

</div>
2 changes: 1 addition & 1 deletion docs/repo-docs/reference/system-environment-variables.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ System environment variables are always overridden by flag values provided direc
</td>
<td>Always ignore the local filesystem cache for all tasks.</td>
</tr>
<tr>
<tr id="turbo_run_summary">
<td>
<code>TURBO_RUN_SUMMARY</code>
</td>
Expand Down
17 changes: 16 additions & 1 deletion docs/src/markdown.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@ import fs from "fs/promises";
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeParse from "rehype-parse";
import rehypeRaw from "rehype-raw";
import { visit } from "unist-util-visit";
import { selectAll } from "hast-util-select";
import GitHubSlugger from "github-slugger";
import matter from "gray-matter";

Expand Down Expand Up @@ -102,6 +104,16 @@ const validateFrontmatter = (path: string, data: Record<string, unknown>) => {
};
};

const getIdsFromHhtmlNodes = (tree: any) => {
const htmlNodes = tree.children
.filter((node: any) => node.type === "html")
.map((node: any) => unified().use(rehypeParse).parse(node.value));

return selectAll("[id]", htmlNodes[0]).map(
(node) => node.properties.id as string
);
};

/**
* Create a map of documents with their paths as keys and
* document content and metadata as values
Expand All @@ -118,7 +130,10 @@ const prepareDocumentMapEntry = async (
const frontMatter = validateFrontmatter(path, data);

const tree = markdownProcessor.parse(content);
const headings = getHeadingsFromMarkdownTree(tree);

const ids = getIdsFromHhtmlNodes(tree);
const headings = [...getHeadingsFromMarkdownTree(tree), ...ids];

const normalizedUrlPath = filePathToUrl(path);

return [normalizedUrlPath, { content, path, headings, frontMatter }];
Expand Down
Loading

0 comments on commit 04b284a

Please sign in to comment.