User Guide Setup in Git

This article describes what lead writers should know about the AdobeDocs repo structure in AdobeDocs and how user guides are structured.

Quick Summary

• The source of truth for Experience Cloud documentation is git.corp.adobe.com/AdobeDocs. The AdobeDocs organization includes repositories (repos) for Enterprise solutions.
• Each repo can contain one or more user guides. However, user guides cannot be nested.
• The TOC.md files must all appear on the same level of the Git structure, usually the level under the ‘help’ directory. Nesting TOC.md directories is not permitted.
• Each user guide consists of a TOC.md file that links to the articles in the guide. An article must appear in the TOC.md in order to be previewed or published. (You can hide articles from appearing in the left nav. See Hiding files.)
• Directory names and article filenames must include only lowercase letters, numbers, and hyphens. No uppercase letters, underscores, or spaces are allowed. (Image and asset files can include uppercase letters and underscores.)

AdobeDocs Repo Structure

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 Locations

Github Private (internal Adobe) Organization - https://git.corp.adobe.com/AdobeDocs/<repo>

Github Public (mirrored for public) Organization - https://github.com/AdobeDocs/<repo>

Structure Details

• Repo Structure - The first level of directories in each repo should be organized by doc type: “help” (for user guides). The main solution repo includes a metadata.md file that includes solution-specific metadata to be used across all the content within the repo. This metadata can be overridden by any TOC.md file in a user guide. For examples, look at the metadata.md and TOC.md files in AdobeDocs repos such as Analytics and Target.
• Help Structure - If the solution includes multiple user guides, the “help” directory should include subdirectories such as “using” and “admin.” The user guides must be on the same level; you cannot have subordinate user guides. If the solution has only one user guide, and you don’t think you’ll add any more user guides, you can add the user guide contents (including the TOC.md and introduction.md files) directory to the “help” directory. If you’re not sure whether you’ll have multiple user guides, the safest approach is to create a “using” directory for the user guide.
• Git Structure Depth - We recommend that the directory structure of the user guide in Git should match the user guide structure, but it’s not required. Only the TOC.md file determines the structure of the user guide contents. You’re welcome to use a flat structure in Git. Remember: the TOC.md determines structure, not the Git structure.
• Assets Directories - Best practice is to create an “assets” directory at any location in which .md files reference images or .zip files. The “assets” directory can have a sub-directory called “do-not-localize” for images that shouldn’t be handed off to loc. For illustration images that require source files, writers should simply include the source file in the “assets” directory alongside the corresponding image file.
• Filenames - The filename should be basic, such as overview.md or processing-rules.md. Do not include the user guide name or topic name in the file, such as 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.

Repo files

In your root repo directory, you should have the following files. Feel free to copy these files from another repo.

• A markdownlint_custom.json that includes additions and exclusions for validating content.
• A .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.
• Git legal files: code-of-conduct.md, contributing.md, and license.md.
• A linkcheckexclude.json file.
• A 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.
• A metadata.md file that determines which links will appear in user guide headers and other repo-level metadata.
• a * redirects.csv* file that includes a list of redirects (old URLs pointing to new URLs).
• A help directory.

User guide files

The user guide level includes the following items.

• A user guide home page file (such as home.md or overview.md) that includes contents for the user guide main page.
• A TOC.md file that defines the user guide structure and includes metadata that applies to all content within the user guide. Writers manually organize this TOC file.
• Markdown (.md) files with article content.
• Assets folders that include image files as well as download files such as .zip and .xls. We recommend that you include an assets folder at the same level as the Markdown file that references the images.

Multiple user guides

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

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.

• Add solution, type, and other metadata.
• Use the git-repo URL to determine the Git location of the links under “Improve This Page” in the right rail.
• (When implemented) To determine the number of levels that appear in the right rail, use mini-toc-levels (2 is the default).

See Metadata.

The TOC.md file

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.

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.

User guide home page

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:

• Brief intro to solution or user guide area with an overview illustration, if possible
• Related user guide – links to other user guides if the solution has multiple user guides
• Get started – Links to getting started, video tutorials, overview page, FAQ, community forum
• New or Featured Articles – Links to release notes, key feature articles

See Designing the Home Page.

Contact Blake if you have questions.

Naming files and folders

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.

How URLs are generated

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

Landing pages

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 the README file in that repo for details.

Contact Bob if you want to create or edit landing pages.

Breadcrumbs

The breadcrumbs that appear at the top of an article are generated based on metadata in the landing pages and in your repo.

Preview and Publish

Whenever you commit to the master 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

When you run activate-exl (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.

Metadata

See Metadata