chore: Update contributing docs (#9456)

* chore: clean up Alert components and improve corresponding docs * chore: document hightlighting and diffs in Code Blocks * chore:remove outdated references to current platform inference from query string * chore: udpate @Inject variables docs * Update docs/contributing/pages/components.mdx * Update docs/contributing/pages/components.mdx * Update docs/contributing/pages/components.mdx * Update docs/contributing/pages/variables.mdx * Update docs/contributing/pages/variables.mdx --------- Co-authored-by: Liza Mock <[email protected]>
getsentry · Mar 15, 2024 · 9c22b0a · 9c22b0a
1 parent b0c5b19
commit 9c22b0a
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 19 deletions.
diff --git a/docs/contributing/pages/components.mdx b/docs/contributing/pages/components.mdx
@@ -24,8 +24,7 @@ This is an alert
 Attributes:
 
 - `title` (string)
-- `level` (string)
-- `dismiss` (boolean)
+- `level` (string: `'info' | 'warning' | 'danger' | 'success'`)
 
 Use this for these types of content:
 
@@ -65,6 +64,52 @@ var foo = "bar";
 ```
 ````
 
+You can bring attention to specific lines in a code block using the `{fromLineA-toLineB}` for ranges,
+or `{lineA,lineB}` for specific lines (or a combination of the two):
+
+```javascript {2} {tabTitle:Example}
+function foo() {
+  let lookat = "me";
+  return "bar";
+}
+```
+
+````markdown {tabTitle:Source}
+```javascript {2}
+function foo() {
+  let lookat = "me";
+  return "bar";
+}
+```
+````
+
+You can also highlight diffs using the `diff` language:
+
+````markdown {tabTitle:Example}
+```diff
+- minus one
++ plus one
+```
+````
+If you want to preserve syntax highlighting, you can add `diff` metadata to any code block
+then annotate the diff with `+` and `-`:
+
+```javascript {diff} {tabTitle:Example}
+function foo() {
+-  return "bar";
++  return "baz";
+}
+```
+
+````markdown {tabTitle:Source}
+```javascript {diff}
+function foo() {
+-  return "bar";
++  return "baz";
+}
+```
+````
+
 ## ConfigKey
 
 Render a heading with a configuration key in the correctly cased format for a given platform.
@@ -86,7 +131,7 @@ Description of send-default-pii
 Attributes:
 
 - `name` (string)
-- `platform` (string) - defaults to the `platform` value from the page context or querystring
+- `platform` (string) - defaults to the `platform` value from the page context
 - `supported` (string[])
 - `notSupported` (string[])
 
@@ -141,14 +186,12 @@ Render an include based on the currently selected `platform` in context.
 Attributes:
 
 - `includePath` (string) - the subfolder within `/includes` to map to
-- `platform` (string) - defaults to the `platform` value from the page context or querystring
+- `platform` (string) - defaults to the `platform` value from the page context
 
 Some notes:
 
 - When the current platform comes from the page context and no matching include is found, the content will be hidden.
 
-- When the current platform comes from the page context path (not the querystring) the platform selector dropdown will be hidden.
-
 - Similar to `PlatformSection`, you can embed content in the block which will render _before_ the given include, but only when an include is available.
 
 - A file named `_default` will be used if no other content matches.
@@ -195,7 +238,7 @@ Something that applies to all platforms, but not javascript or node.
 
 Attributes:
 
-- `platform` (string) - defaults to the `platform` value from the page context or querystring
+- `platform` (string) - defaults to the `platform` value from the page context
 - `supported` (string[])
 - `notSupported` (string[])
 - `noGuides` (boolean) - hide this on all guides (takes precedence over `supported`/`notSupported`)
diff --git a/docs/contributing/pages/variables.mdx b/docs/contributing/pages/variables.mdx
@@ -3,7 +3,8 @@ title: Markdown Variables
 noindex: true
 ---
 
-A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way. The variables available are globally scoped and configured within `gatsby-config.js` (via `gatsby-remark-variables`).
+A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way.
+The variables available are globally scoped and configured within `remark-variables.js`.
 
 For example:
 
@@ -15,9 +16,11 @@ JavaScript SDK: {{@inject packages.version("sentry.javascript.browser") }}
 JavaScript SDK: {{\@inject packages.version("sentry.javascript.browser") }}
 ```
 
-In this case, we expose `packages` as an accessor in the package registry which is why there is a `packages.version` function available. Additional, we expose a default context variable of `page` which contains the frontmatter of the given markdown node. For example, `{{\@inject page.title }}`.
+In this case, we expose `packages` as an accessor in the package registry, which is why there's a `packages.version` function available. Additionally, we expose a default context variable of `page`, which contains the frontmatter of the given markdown node. For example, `{{\@inject page.title }}`.
 
-When a variable call is invalid (or errors), or doesn't match something in the known scope, it will produce an error. If you need to escape an expression you can add a leading `\` to the `@inject`.
+When a variable call is invalid (or errors), or doesn't match something in the known scope, it will produce an error message in the output in development mode. It will force the build to fail in production.
+
+To escape an expression add a leading `\` to the `@inject`.
 
 ## `packages`
 

diff --git a/src/components/alert.tsx b/src/components/alert.tsx
@@ -2,13 +2,11 @@
 
 type Props = {
   children?: any;
-  deepLink?: string;
-  dismiss?: boolean;
   level?: 'info' | 'warning' | 'danger' | 'success' | '';
   title?: string;
 };
 
-export function Alert({title, children, level, deepLink, dismiss = false}: Props) {
+export function Alert({title, children, level}: Props) {
   let className = 'alert';
   if (level) {
     className += ` alert-${level}`;
@@ -17,12 +15,7 @@ export function Alert({title, children, level, deepLink, dismiss = false}: Props
     className += ' markdown-text-only';
   }
   return (
-    <div className={className} role="alert" id={deepLink}>
-      {dismiss && (
-        <button type="button" className="close" data-dismiss="alert" aria-label="Close">
-          <span aria-hidden="true">&times;</span>
-        </button>
-      )}
+    <div className={className} role="alert">
       {title && <h5 className="no_toc">{title}</h5>}
       <div className="alert-body content-flush-bottom">{children}</div>
     </div>