Fountainhead makes writing guides easy with these features:
\n/guides will be observed by Ember CLI and live reload on change.We hope that these conveniences inspire you to write guides for your project!\nSemantically named variables and methods go a long way towards self documenting code,\nand API documentation helps for reference, but guides bridge the gap of providing\nproject overviews, architecture considerations and the why of code. For\ncontributors looking to get started with projects, these aspects can be really hard\nto deciper without a guide!
\n{{#fountainhead-header tagName=\"h2\" elementId=\"guide-discovery\"}}Guide Discovery{{/fountainhead-header}}\nThere are two ways Fountainhead can be configured to consume guides:
\n/guidesfountainhead.guides config.Fountainhead will automatically consume any guide that is saved in /guides. The\nguides will be consumed alphabetically by file path+name and the order of guides in\nthe the navbar will match this order. See Ordering Guides\n for info on controlling the guide display order.
Guides from any location in your project can be consumed using the\nfountainhead.guides config in your fountainhead.js config file. Guides must be an\narray and can include paths to files or directories.
{{#fountainhead-alert canDismiss=false brand='info'}}\n{{fountainhead-svg svgId='info'}} PRO TIP
\nYou can create domain specific guides in your project source and include them in your\ndocumentation using the guides config. This can be especially helpful\nfor project features that require architecture/background knowledge that doesn't\nfit explicitly into the API documentation.\n{{/fountainhead-alert}}
For example, this project has all of the setup and how-to guides in the /guides\ndirectory, but is also configured to include Release guides and an architecture\noverview of scroll targeting using the guides config:
module.exports = {\n guides: [\n 'addon/scroll-target.md', // Specific file in the addon directory\n 'releases' // Folder of release guides in project root\n ],\n}\nYou can include a front matter block in\na guide to easily configure meta data for the guide. The following configurations\ncan be used to control how your guide is displayed:
\n| Attribute | \n\n | Use | \n
|---|---|---|
id | \nRequired | \nUnique identifier for a guide. Also used as the url model id | \n
[linkText] | \nOptional | \nAnchor text used in guide navigation | \n
[title] | \nOptional | \nPage header text | \n
[group] | \nOptional | \nParent label to nest a set of groups under | \n
[private] | \nOptional | \nWhen true, guide is not parsed or included in nav | \n
[protected] | \nOptional | \nWhen true, guide is parsed and saved, but not included in meta | \n
---\nid: writing-guides\nlinkText: Writing Guides\ntitle: Writing Guides with Ember Fountainhead\ngroup: How Tos\n---\n\nEmber Fountainhead makes writing guides easy...\nThe private and protected meta attributes can be used to control what guides are\nconsumed and displayed by Fountainhead.
private: guides marked private are not parsed, saved or included in the meta for\nyour documentation. These guides are ignored by Fountainhead.protected: guides marked protected are parsed and saved into /docs/guides, but\nthey are not included in your documentation meta. This is useful if you would like\nto write guides to link to interally, but not include them in the guide navigation.Sets of guides can be grouped together in the guide navigation using a group\nattribute. This is useful if you have a set of guides that are related, but too long\nto contain in a single guide. You can create groups for your guides in two ways:
group attribute in any guide. If that group doesn't exist\nFountainhead will create one and add that group to it.fountainhead.guides config (This\ncan be helfpul for guide ordering): module.exports = {\n guides: [\n { id: 'How Tos' }, // Object literals are interpreted as a group config\n ],\n }\nGuides are included in the guide navigation in this order:
\n/guides alphabetically by filepath+namefountainhead.guides configuration arrayIf you want to control the order of the guides listed in the navigation, you can use\nordered file names and folders, eg: 1_first-guide.md, 2_second-guide.md. See the\nguides directory\nfor Fountainhead for a complex example.