Quick notes

src/pages/blocks/columns/columns-with-video.md

@@ -10,15 +10,15 @@ description: Learn how to use the Columns block with videos.
 ```markdown
 <Columns slots="video, heading, text, buttons" repeat="2" />
 
-[Video alt description](https://raw.githubusercontent.com/AdobeDocs/dev-docs-reference/main/src/pages/assets/example-video.mp4)
+[Video alt description](../../assets/example-video.mp4)
 
 ### Feature One
 
 Description of the first feature.
 
 [Learn more](https://example.com)
 
-[Video alt description](https://raw.githubusercontent.com/AdobeDocs/dev-docs-reference/main/src/pages/assets/example-video.mp4)
+[Video alt description](../../assets/example-video.mp4)
 
 ### Feature Two
 
@@ -31,15 +31,15 @@ Description of the second feature.
 
 <Columns slots="video, heading, text, buttons" repeat="2" />
 
-[Video alt description](https://raw.githubusercontent.com/AdobeDocs/dev-docs-reference/main/src/pages/assets/example-video.mp4)
+[Video alt description](../../assets/example-video.mp4)
 
 ### Feature One
 
 Description of the first feature.
 
 [Learn more](https://example.com)
 
-[Video alt description](https://raw.githubusercontent.com/AdobeDocs/dev-docs-reference/main/src/pages/assets/example-video.mp4)
+[Video alt description](../../assets/example-video.mp4)
 
 ### Feature Two
 

src/pages/blocks/superhero/halfwidth/with-background-image-and-video.md

@@ -12,7 +12,7 @@ Superhero half width variant with background image and video
 
 ![Gradient background](../../../assets/vertical-gradient.png)
 
-[video_url](https://example.com/demo-video.mp4)
+[video_url](../../../assets/example-video.mp4)
 
 # Page Heading
 
@@ -26,7 +26,7 @@ This is a sample description text for the superhero block.
 
 ![Gradient background](../../../assets/vertical-gradient.png)
 
-[video_url](https://raw.githubusercontent.com/AdobeDocs/dev-docs-reference/refs/heads/main/src/pages/assets/example-videp.mp4)
+[video_url](../../../assets/example-video.mp4)
 
 # Page Heading
 

src/pages/faq/index.md

@@ -8,14 +8,18 @@ description: A guide with FAQ about the ADP Developer Site
 ## How do I link PDF or ZIP files for download or viewing?
 To host and link PDF files (or other files like `ZIP` or `.d.ts`), use a URL and use relative path to file within `src/pages`:
 
-`[ZIP](./assets/process.zip)`
-`[PDF for download](./assets/example.pdf)`
+`[ZIP](./assets/process.zip)` \<br/\> 
+`[PDF for download](./assets/example.pdf)` \<br/\> 
 
+`JSON` files in `src/pages` must be in AEM EDS format or deployments will fail. JSON files that aren't in AEM EDS format (such as Redocly API spec files) must be placed in the `static` folder and can be linked using a relative path: \<br/\> 
+
+`[example JSON file](../../static/petstore.json)
+`
 ## Where can I upload videos?
 
-To use videos in blocks that accept video attributes, you need to provide a URL. Here are your options for uploading and hosting videos:
+To use videos in blocks that accept video attributes, you need to provide a URL or if uploaded under `src/pages` they can use a relative path. Here are your options for uploading and hosting videos:
 
-**GitHub**: Commit your video to your GitHub repository and copy the raw GitHub URL.
+**GitHub**: Commit your video to your GitHub repository and link to it using a relative path. [See Superhero with video](../blocks/superhero/halfwidth/with-background-image-and-video.md)
 
 **Google Drive** (with 2-minute limit): Upload your video to Google Drive, open it, use the AEM Sidekick extension to publish, then copy the URL. Videos uploaded to Google Drive have a 2-minute limit.
 

src/pages/getting-started/dev-docs/best-practices/index.md

@@ -39,6 +39,20 @@ description: Best practices and troubleshooting tips for migrating your document
   - Relative links should include file name and extension (ex: `index.md` or other `.md` file)
     - except for anchor links that are in the current page (e.g. `[description](#anchor)`)
     - note: anchor links don't work in local development - deploy to stage to test
+  - **Reference-style links for `.md` files**:
+    - You can list targets once at the bottom of the file and reference them by label in the body. This keeps long paths out of inline text.
+    - Example:
+
+```
+To configure credentials for your integration, see [Authentication][2].
+
+[//]: # (Links)
+[1]: /docs/overview/index.md
+[2]: /reference/authentication/index.md
+[3]: /guides/release-notes/index.md
+
+```
+
   - To open link as external, use the query string `?aio_external` in your URL:
     - Example: [https://github.com/AdobeDocs/adp-devsite-github-actions-test/blob/main/src/pages/test/test-hr-0.md?plain=1#L13](https://github.com/AdobeDocs/adp-devsite-github-actions-test/blob/main/src/pages/test/test-hr-0.md?plain=1#L13)
     - This will have to open the external link manually.
@@ -55,10 +69,27 @@ description: Best practices and troubleshooting tips for migrating your document
   - In Gatsby, invalid URLs that have unnecessary trailing slashes will work. However, in EDS they won't work
   - `redirects.json` will redirect Gatsby bookmarks (from invalid form to correct form). It's best to do this for a limited period of time, around 4-6 weeks.
 
-- **Links to other file types than .md and .json needs to use raw github links for now**:
-  - example: [https://github.com/AdobeDocs/adp-devsite-github-actions-test/blob/ced7a472d45d7d911f391f79706a3e00b7bad46a/src/pages/test/mp4.md?plain=1#L1](https://github.com/AdobeDocs/adp-devsite-github-actions-test/blob/ced7a472d45d7d911f391f79706a3e00b7bad46a/src/pages/test/mp4.md?plain=1#L1)
-    - mp4 file: `https://raw.githubusercontent.com/AdobeDocs/adp-devsite-github-actions-test/refs/heads/main/src/pages/assets/example-video.mp4`
-  - We have a ticket open to fix this
+- **Links to other file types than .md and .json can use relative paths**:
+  - `[ZIP](./assets/process.zip)` \<br/\> 
+`[PDF for download](./assets/example.pdf)` \<br/\> 
+  - In blocks, like Columns or Superhero, images and videos can also be in a relative path:
+```markdown
+<Superhero slots="fullWidthBackground, video, heading, text, buttons" variant="halfWidth" textColor="white" overGradient />
+
+![Gradient background](../../../assets/vertical-gradient.png)
+
+[video_url](../../../assets/example-video.mp4)
+
+# Page Heading
+
+This is a sample description text for the superhero block.
+
+* [Get Started](https://example.com/getting-started)
+* [View Examples](https://example.com/examples)
+```
+- **GitHub URLs for files that end in `.md`**:
+  - Use `%2E` in place of the period before `md` in the path so the URL resolves
+  - Example: `[README on GitHub](https://github.com/AdobeDocs/dev-docs-reference/blob/main/README%2Emd)` — use `%2E` instead of `.` before `md` in the path segment (not `...README.md`). We have a [ticket](https://jira.corp.adobe.com/browse/DEVSITE-2375) logged to fix this so you don't need to use this workaround
 - **Fix dead links**:
   - `$npm run lint --dead-links-only`: lists dead links. Run to prevent 404s. Check your `package.json` file for more linting scripts
   - More information: [Linting Guide](../../../deploy/lint.md)