We have three main audiences:
We can't assume that everybody understands the conversational shorthand Flex veterans use. Write for a person of good will who is reading to find out, and who wants to get to the next needed nugget of knowledge soon so they can go and make progress on the app they are working on.
We produce four flavors of documentation:
No one flavor is better in all circumstances than the others. All contributions strengthen Royale by expanding the number of people who can find the answers they need to create applications.
.md page starts with “front matter” structured like this:
--- # Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. layout: docpage title: README description: short description of the page that will help social networks to show appropriate info permalink: /friendly-url ---
Use HTML comments at the top of the document for any explanatory notes for the doc team (
<!-- Not finished yet - Andrew -->) and for provenance when adapting existing material for Royale purposes (
<!-- Created by Peter Ent, modified by Tom Chiverton, as part of FlexJS documentation-->).
%20statements, and add the markdown specification. The file name should be
Another_important_thing.md. These details are important for SEO, human readability, and readability by assistive devices.
permalink: /another-important-thing. If the file is
widgetsfolder, its permalink would be
In the .md files, links have to be full paths without the leading slash. The link to the published HTML version of features/as3.md, is
[AS3](features/as3.html), but we want to use permalinks so the link to use should be:
and the permalink on that page will be,
without the leading “/”. Links are case-sensitive, and you need to insert
%20 for any space that appears in the target file's name. Check the guidance about file names, above.
When linking to locations not in the help-docs stack, including other pages in the Royale website, clicking the link should open a new browser window or tab so the reader does not lose their place in the help docs:
Search is done thanks to Algolia DocSearch.
* [Algolia DocSearch Docs](https://community.algolia.com/docsearch/what-is-docsearch.html)
Install Ruby+Devkit. Ruby is required to run Jekyll.
If you want to provide a local configuration, copy
To build the docs, run the following command:
jekyll build --watch --config _config.yml
The website will be rendered inside the
To browse the docs using built-in Jekyll server, run the following command:
You might need the following for automatic regeneration:
jekyll serve --force_polling
The website will be available at