Add more documentation about the @Image source value
#1167
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Also, add some information from the images article to the @image directive documentation. rdar://145303029
… to the 2 times scaled display mode
1 task
anferbui
reviewed
Mar 17, 2025
| ```` | ||
|
|
||
| Images can exist anywhere in your code base, but it's good practice to centralize them in a resources folder. You create this folder in your documentation catalog. Within your code base, image names must be unique. Images must be in *.png*, *.jpg*, *.jpeg*, *.svg*, or *.gif* format. | ||
| Images can exist anywhere in your documentation catalog ('.docc' directory). but it's good practice to use subdirectories to organize the content and assets in your documentation. | ||
| Regardless of organization within your catalog, each image need to have a unique name. |
There was a problem hiding this comment.
Suggested change
| Regardless of organization within your catalog, each image need to have a unique name. | |
| Regardless of organization within your catalog, each image needs to have a unique name. |
|
|
||
| - Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with tutorial\. | ||
| - Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with tutorial. |
There was a problem hiding this comment.
It might be useful to differentiate the prefix with some sort of styling, such as quotes or code-styling
Suggested change
| - Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with tutorial. | |
| - Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with "tutorial". |
There was a problem hiding this comment.
I mostly wanted to remove the extra character on that line. I agree that quoting the the prefix would distinguish it better.
However, now that I read the tip more closely I feel like it's a bit silly and could maybe go away entirely.
Suggested change
| - Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with tutorial. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Bug/issue #, if applicable: rdar://145303029
Summary
90543ce updates the
@Imagedirective documentation to include more information about the format of thesourceparameter. Some of this information was already available in the Adding Images to Your Content article but some of it is specific to directive string parameters.It also makes some minor clarifications and corrections this documentation:
b3e0430 consistently omits unnecessary quotation marks and file extensions in
@Imageexamples in other DocC documentation.Dependencies
None
Testing
Locally build the DocCDocumentation.docc catalog and preview the
@Imagedirective page.Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
[ ] Added testsNot applicable[ ] Ran theNot applicable./bin/testscript and it succeeded