This article describes what lead writers should know about the AdobeDocs repo structure in AdobeDocs and how user guides are structured.
Watch this Git/AdobeDocs overview video
AdobeDocs is the GitHub organization that contains Experience Cloud documentation. Within the GitHub Org, each solution has its own repository. Within each repo, the directory structure is as follows.
Github Enterprise (internal Adobe) Organization - https://git.corp.adobe.com/AdobeDocs/<repo>
Github Public (mirrored for public) Organization - https://github.com/AdobeDocs/<repo>
admin-getting-started-processing-rules-overview.md
. Instead, keep it simple: processing-rules-overview.md
. The user guide structure based on TOC.md contents will be reflected in the URL. Remember: No uppercase letters or underscore (_) characters in your filenames.In your root repo directory, you should have the following files. Feel free to copy these files from another repo.
markdownlint_custom.json
that includes additions and exclusions for validating content..gitignore
file that excludes certain files such as .DS_store
and other Mac OS system files from being tracked and included in pushes to the server. This helps Mac users avoid irritating conflict messages for system files in GitHub Desktop.code-of-conduct.md
, contributing.md
, and license.md
.linkcheckexclude.json
file.readme.md
file that provides information to contributors about editing our documentation. This readme.md is a “loose” file for reference for collaborators using Git. It is not published as part of the user guide.metadata.md
file that determines which links will appear in user guide headers and other repo-level metadata.redirects.csv
* file that includes a list of redirects (old URLs pointing to new URLs).The user guide level includes the following items.
home.md
or overview.md
) that includes contents for the user guide main page.If your repo includes multiple user guides, the user guides MUST be on the same level. You cannot have nested user guides.
If your repo includes multiple user guides, create user guide subdirectories within the help
directory.
To see an example, look at the Analytics structure in Git. The help folder includes multiple subdirectories. Subdirectories represent a user guide with a separate TOC. For example, the admin
subdirectory includes the Analytics Admin Guide TOC, and the analyze
subdirectory includes the Analysis Workspace Guide TOC.
The metadata.md file is where you can add global metadata for all guides in your repo. If you want to apply different metadata for an individual guide or article, you can do so.
solution
, type
, and other metadata.git-repo
URL to determine the Git location of the links under “Improve This Page” in the right rail.mini-toc-levels
(2 is the default).See Metadata.
The TOC.md file determines the user guide content, structure, and appearance in the left navigation. Use nested bullet lists to determine the structure. Use the appropriate syntax for section headings and links. See Editing TOC files.
The TOC.md file also includes IDs that determine page URLs. See How URLs are generated.
Pay close attention to the syntax you use in the TOC.md file. Using an incorrect character can result in validation errors.
See Working with TOC.md files.
Article names in the TOC.md file
Shorten article names to be concise and to avoid wrapping. For example, remove the solution name from the article title in the TOC file.
The article names in brackets [ ]
appear in the left navigation rail. This text is localized. The filename in parentheses is not localized.
Parent sections
Make sure that each parent section is not a hyperlink (don’t use brackets for the name).
Make sure that each parent section has a unique section ID, such as {#admin-overview}
.
This section ID is used an article URLs, so use a logical ID (lowercase and hyphenated), and avoid editing the section ID once you push content live. If you do need to edit the section ID after you push content live, you’ll change the article URL, so add redirects as needed.
Metadata
The metadata at the top of the TOC.md file applies to all content within the user guide. However, article metadata can override the TOC.md metadata. For example, if you set metadata in the TOC.md file as product: analytics
, it applies to all articles in the user guide. However, if you specify product: analytics, target
in an article, that article metadata overrides the TOC metadata. See Metadata.
The user guide needs a home page. In each user guide directory, create a home page article, and add this article as the first article in the TOC.md file.
This home page should have a consistent look and feel across the products. It should have a friendly design that points users to key resources. However, it should not be used as a full table of contents. That would be redundant with the left navigation TOC.
Include the following items:
Contact Blake if you have questions.
All Markdown filenames that are part of the user guide must be lowercase and hyphenated to comply with Adobe URL standards. Don’t use capital letters or underscores. Example: processing-rules.md
Git folder names should also be lowercase and hyphenated. No caps or underscores.
Heading IDs (anchor IDs) such as ## Heading example {#heading-example}
and section IDs in the TOC should be lowercase and hyphenated.
Image names and other asset files can include capital letters and underscores, but we recommend using lowercase letters and hyphens.
URLs are determined by the Git repo name and the properties in the TOC.md file.
Again, avoid editing the IDs in the TOC.md unless it’s absolutely necessary.
See Moving, Renaming, and Reorganizing Content
The landing pages, including the main landing page, are created and edited by the SCCM team. The markdown used in the landing-pages.en
repo has different syntax and validation rules than that used in other AdobeDocs repos. See Landing pages.
Contact Bob if you want to create or edit landing pages.
The breadcrumbs that appear at the top of an article are generated based on metadata in the landing pages and in your repo.
Whenever you commit to the main branch, the content is validated on Jenkins. If the content is valid, you can preview the content at this location available only to Adobe users:
https://experienceleague.corp.adobe.com/docs/<repo-name>/<guide-id>/<homepage>.html
If you want to find the URL of a new repo, edit the page and commit the change to the main branch. The Slack summary will include a link of the edited article.
When you run activate-new (or if your repo is set to auto-activate), your changes are pushed live:
https://experienceleague.adobe.com/docs/<repo-name>/<guide-id>/<homepage>.html
See Publish.
Note that the stage workflow is currently not supported. The staging
branch is ignored in Experience League but available for a short time in docs-stg.corp.adobe.com.
See Metadata