Skip to content

Commit

Permalink
Merge pull request #7678 from braze-inc/internetisaiah-patch-3
Browse files Browse the repository at this point in the history 
Update cross_referencing.md
  • Loading branch information
@rachel-feinberg
rachel-feinberg authored Jul 12, 2024
2 parents 849b946 + 2c537a9 commit 0bd70a2
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 124 deletions.
64 changes: 7 additions & 57 deletions _docs/_contributing/content_management/cross_referencing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,14 @@ noindex: true

## Create a cross-reference

When creating a cross-reference, you can either use the in-line method or reference-style method. The in-line method prioritizes clarity, while the reference-style method prioritizes readability.
{% alert important %}
Because Liquid's {% raw %}`{% tab %}`{% endraw %} tag does not support reference-style links, only in-line links are documented below. Existing reference links will continue to work, but are no longer recommended.
{% endalert %}

{% tabs %}
{% tab in-line %}
{% tab Markdown %}
Open the relevant Markdown file, then create your in-line link.

{% subtabs %}
{% subtab Markdown %}

{% raw %}
```markdown
[LINK_TEXT]({{site.baseurl}}/SHORT_URL)
Expand All @@ -44,9 +43,10 @@ Your in-line link should be similar to the following:
Before continuing, [create your SSH token]({{site.baseurl}}/docs/developer_guide/platform_wide/sdk_authentication).
```
{% endraw %}
{% endsubtab %}
{% endtab %}

{% subtab HTML %}
{% tab HTML %}
Open the relevant Markdown file, then create your in-line link.

{% raw %}
```markdown
Expand All @@ -69,55 +69,5 @@ Your in-line link should be similar to the following:
To learn about the different custom attribute data types you can use to segment users, view <a href="/docs/user_guide/data_and_analytics/custom_data/custom_attributes/#custom-attribute-data-types">Custom attribute data types</a>.
```
{% endraw %}
{% endsubtab %}
{% endsubtabs %}

{% endtab %}

{% tab reference-style %}
Open the relevant Markdown file, then create your reference-style link.

```markdown
[LINK_TEXT][REFERENCE_NUMBER]
```

Replace the following:

| Placeholder | Description |
|--------------------|--------------------------------------------------------------------------|
| `LINK_TEXT` | The page title or related action. |
| `REFERENCE_NUMBER` | Assign any positive integer that's not already assigned to another reference-style link on this page. |
{: .reset-td-br-1 .reset-td-br-2}

Your references should be similar to the following:

```markdown
Before continuing, [create your SSH token][2]. When you're finished, see [Step 2: Uploading your token][5].
```

At the bottom of the page, you'll add the related links.

{% raw %}
```markdown
[REFERENCE_NUMBER]: {{site.baseurl}}SHORT_URL
```
{% endraw %}

Replace the following:

| Placeholder | Description |
|--------------------|---------------------------------------------------------|
| `REFERENCE_NUMBER` | The number of the reference you'd like to link to. |
| `SHORT_URL` | The page URL with `https://www.braze.com/docs` removed. |
{: .reset-td-br-1 .reset-td-br-2}

Your links should be similar to the following:

{% raw %}
```markdown
[2]: {{site.baseurl}}/developer_guide/platform_wide/sdk_authentication/
[5]: {{site.baseurl}}/developer_guide/platform_wide/swift#step-2-uploading-your-token
```
{% endraw %}
{% endtab %}
{% endtabs %}
70 changes: 3 additions & 67 deletions _docs/_contributing/content_management/images.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,10 @@ braze-docs

### Step 2: Link to the image

When linking to your new image, you can either use in-line or reference-style syntax. In-line syntax prioritizes clarity, while reference-style syntax prioritizes readability.
{% alert important %}
Since Liquid's {% raw %}`{% tab %}`{% endraw %} tag does not support reference-style links, only in-line links are documented below. Existing reference links will continue to work, but are no longer recommended.
{% endalert %}

{% tabs %}
{% tab in-line %}
In your Markdown file, link to your new image using the in-line syntax.

{% raw %}
Expand All @@ -73,58 +73,6 @@ Your in-line image should be similar to the following:
![The form for creating a new pull request on GitHub.]({% image_buster /assets/img/contributing/getting_started/github_pull_request.png %})
```
{% endraw %}
{% endtab %}

{% tab reference-style %}
In your Markdown file, link to your new image using the reference-style syntax.

{% raw %}
```markdown
![ALT_TEXT.][REFERENCE_NUMBER]
```
{% endraw %}

Replace the following:

| Placeholder | Description |
|--------------------|-------------------------------------------------------------------------------------------------------------------------|
| `ALT_TEXT` | The alt text for the image. This is required to make Braze Docs equally accessible for those using screen readers. |
| `REFERENCE_NUMBER` | Assign any positive integer that's not already assigned to another reference-style link on this page. |
{: .reset-td-br-1 .reset-td-br-2}

Your in-line image should be similar to the following:

{% raw %}
```markdown
![The form for creating a new pull request on GitHub.][10]
```
{% endraw %}

At the bottom of the page, add your reference.

{% raw %}
```markdown
[REFERENCE_NUMBER]: {% image_buster /assets/img/DIRECTORY/IMAGE.png %}
```
{% endraw %}

Replace the following:

| Placeholder | Description |
|--------------------|---------------------------------------------------------|
| `REFERENCE_NUMBER` | The number of the reference you'd like to link to. |
| `IMAGE` | The relative path to your image starting from the `img` directory. |
{: .reset-td-br-1 .reset-td-br-2}

Your links should be similar to the following:

{% raw %}
```markdown
[10]: {% image_buster /assets/img/contributing/getting_started/github_pull_request.png %}
```
{% endraw %}
{% endtab %}
{% endtabs %}

### Step 3: Set the image's maximum width (optional)

Expand All @@ -138,23 +86,11 @@ You can set the image's maximum width by appending the following Liquid code to

Replace `NUMBER` with the maximum width you'd like to set as a percentage. Your image link should be similar to the following:

{% tabs %}
{% tab in-line %}
{% raw %}
```markdown
![The form for creating a new pull request on GitHub.]({% image_buster /assets/img/contributing/getting_started/github_pull_request.png %}){: style="max-width:65%;"}
```
{% endraw %}
{% endtab %}

{% tab reference-style %}
{% raw %}
```markdown
![The form for creating a new pull request on GitHub.][10]{: style="max-width:65%;"}
```
{% endraw %}
{% endtab %}
{% endtabs %}

## Updating an image

Expand Down

0 comments on commit 0bd70a2

Please sign in to comment.