Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: options one-pager #9533

Merged
merged 11 commits into from
Dec 5, 2024
Merged

docs: options one-pager #9533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
067f162
wip
anthonyshew Nov 27, 2024
30044d6
[WIP] docs: Options cheat sheet
anthonyshew Nov 27, 2024
727babd
Done going through Env Vars doc.
anthonyshew Dec 2, 2024
6f7abad
WIP
anthonyshew Dec 3, 2024
37c7057
Merge branch 'main' into shew-0e55f
anthonyshew Dec 3, 2024
2e81e10
WIP
anthonyshew Dec 3, 2024
4eb93c6
WIP
anthonyshew Dec 4, 2024
df27925
WIP
anthonyshew Dec 4, 2024
064033d
WIP
anthonyshew Dec 5, 2024
15992ef
WIP
anthonyshew Dec 5, 2024
9105105
WIP
anthonyshew Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/package.json
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading