Summary

Learn how to structure and use the content in the most efficient way. The secret is to use to the maximum extent the features made available, out of which importing external content (at build time or at run time) is the most powerful since it allows establishing single source of truth for a lot of repetitive pieces of content that you may need to use in your documents. As such, when modifying this kind of pieces of content, you don’t have to remember in which document you place it, only modify the source and the pice of content will appear in its new version in all document where is placed.

There are two types of content that you can use in your documents:

• content directly included in your documents
• content imported from external sources

We define an external source as a source of content which is outside the current document. An external source can be another file from your documentation or a file from an external Github repository (public or private). External sources are very important because allows you to create reusable pieces of content which can be placed anywhere within your documentation. The content from external sources (external content) can be rendered at build time or at run time. These beeing said, it becomes clear that it is very important the way in which you organise your documentation.

Organise documents

As example, we will use the structure of Docaroo documentation. The documents are located in doc-contents folder inside the project folder. We name doc-contents as the docs root folder.

📁 doc-contents/
├── 📁 _components
│   ├── 📄 alerts.md
│   ├── 📄 card.md
│   ├── 📄 components.md
│   ├── 📁 download-link
│   │   ├── 📄 download-link.md
│   │   └── 📄 lorem-ipsum.pdf
│   ├── 📄 faq-item.md
│   ├── 📄 images.md
│   ├── 📄 link-btn.md
│   ├── 📄 rich-media.md
│   ├── 📄 scroll-spy.md
│   ├── 📁 xlsx-to-html-chart
│   │   ├── 📄 corrected-example.xlsx
│   │   ├── 📄 test-file.xlsx
│   │   └── 📄 xlsx-to-html-chart.md
│   └── 📁 xlsx-to-html-table
│       ├── 📁 tables
│       │   └── 📄 test-file.xlsx
│       ├── 📄 test-file.xlsx
│       └── 📄 xlsx-to-html-table.md
├── 📁 _content
│   ├── 📄 content-items.md
│   ├── 📄 content.md
│   └── 📄 external-content.md
├── 📁 _experiments
│   ├── 📁 docx-summary
│   │   ├── 📄 docx-summary.md
│   │   ├── 📄 pe.docx
│   │   ├── 📄 pe__word_summary.txt
│   │   ├── 📄 pr.docx
│   │   ├── 📄 pr__word_summary.txt
│   │   ├── 📄 pt.docx
│   │   └── 📄 pt__word_summary.txt
│   ├── 📄 experiments.md
│   └── 📁 pdf-summary
│       ├── 📄 pdf-summary.md
│       ├── 📄 pe.pdf
│       ├── 📄 pe__pdf_firstpage.png
│       ├── 📄 pe__pdf_summary.txt
│       ├── 📄 pr.pdf
│       ├── 📄 pr__pdf_firstpage.png
│       ├── 📄 pr__pdf_summary.txt
│       ├── 📄 pt.pdf
│       ├── 📄 pt__pdf_firstpage.png
│       └── 📄 pt__pdf_summary.txt
├── 📁 _faq
│   ├── 📄 q0.md
│   ├── 📄 q01.md
│   ├── 📄 q1.md
│   ├── 📄 q2.md
│   ├── 📄 q3.md
│   ├── 📄 q4.md
│   ├── 📄 q6.md
│   ├── 📄 q7.md
│   ├── 📄 q71.md
│   ├── 📄 q8.md
│   └── 📄 q9.md
├── 📁 _tools
│   ├── 📄 cat-info.md
│   ├── 📄 faq.md
│   ├── 📄 site-pages.md
│   └── 📄 tag-info.md
├── 📁 downloads
│   └── 📄 lorem-ipsum.pdf
├── 📁 general
│   └── 📄 404.html
├── 📄 get-started.md
├── 📄 intro.md
└── 📁 partials
    ├── 📁 card-gallery-demo
    │   ├── 📄 c1.md
    │   ├── 📄 c2.md
    │   ├── 📄 c3.md
    │   └── 📄 c4.md
    ├── 📁 errors-and-warnings
    │   └── 📄 wrong-link-btn-type.md
    ├── 📁 external-content-demo
    │   ├── 📄 alert-content.md
    │   ├── 📄 card-content-aside-demo.md
    │   ├── 📄 card-content-demo.md
    │   ├── 📄 card-gallery-c1.md
    │   ├── 📄 card-gallery-c2.md
    │   ├── 📄 card-gallery-c3.md
    │   ├── 📄 card-gallery-c4.md
    │   ├── 📄 ec1.md
    │   ├── 📄 ec2.md
    │   └── 📄 faq-demo.md
    ├── 📁 media
    │   ├── 📄 c1-tr-1.png
    │   ├── 📄 c1-tr-2.png
    │   ├── 📄 doc-site-s.png
    │   ├── 📄 doc-site-tr.png
    │   ├── 📄 girl-1.png
    │   ├── 📄 home-600.png
    │   ├── 📄 home-s.png
    │   ├── 📄 human-600.png
    │   ├── 📄 joy-s.png
    │   ├── 📄 man-s.png
    │   ├── 📄 man-thinking.png
    │   ├── 📄 smile-600.png
    │   └── 📄 w2s-gr-s.png
    └── 📁 scroll-spy
        ├── 📁 demo-combined-scroll-spy
        │   ├── 📄 item1.md
        │   └── 📄 item2.md
        └── 📁 demo-scroll-spy
            ├── 📄 item1.md
            ├── 📄 item2.md
            ├── 📄 item3.md
            ├── 📄 item4.md
            └── 📄 item5.md

Following the structure of Docaroo documents, you can organise your documentation based on the next recommendations:

1. Do not rename the docs root folder, it has to be always named doc-contents
2. Do not remove the following sub-folders:
   • general: it contains some mandatory html files (currently 404.html, which you can customise as you need)
   • _tools: it contains the main tools made available by Docaroo for easy work documents and taxonomies as well as faq page if this feature is active
   • _faq: if faq feature is active for the site, this sub-folder contains the questions and answers
3. Use collections of documents to group your documents in relevant sections. A collection is a folder starting with _ and properly declared in _config.yml
4. For easy find all document’s components (such as images), you can put each document on it’s own folder together with the media files that it uses. This approach may be bette than having a single source of many media files. However, large media files (such as videos) should not be stored in the docs root folder and to be rendered/played from specialized and much faster sources (such as Vimeo or Youtube). We provide dedicated components for such situations.

Observe the files in partials sub-folder. These files doesn’t have regular front matter and should stay like this to avoid them to be rendered as documents at build time.