Add SilverStripe markdown documentation.
This commit is contained in:
Will Rossiter
parent
17527f63d3
commit
b95191ea3d
|
|
@ -0,0 +1,115 @@
|
|||
# SilverStripe Markdown Syntax
|
||||
|
||||
As Markdown by default is quite limited and not well suited for technical documentation,
|
||||
the SilverStripe project relies on certain syntax additions. As a base syntax, we use
|
||||
the [Markdown Extra](http://michelf.com/projects/php-markdown/extra/) format, which provides us
|
||||
with support for tables, definition lists, code blocks and inline HTML.
|
||||
|
||||
**Please read the [Markdown](http://daringfireball.net/projects/markdown/syntax) and
|
||||
[Markdown Extra](http://michelf.com/projects/php-markdown/extra/) documentation for a syntax overview**
|
||||
|
||||
On top of that, we have added syntax that is only resolved by our custom parser.
|
||||
The goal is to keep the customization to a necessary minimum,
|
||||
and HTML output should still be readable with our custom markup unparsed.
|
||||
|
||||
## Rendering
|
||||
|
||||
While most of the Markdown syntax is parseable by all common implementations,
|
||||
the special syntax is relying on a custom SilverStripe project that powers `http://doc.silverstripe.org`.
|
||||
|
||||
The website a standard SilverStripe installation with the [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer/)
|
||||
module installed (see module [README](https://github.com/silverstripe/silverstripe-docsviewer/blob/master/README.md) and
|
||||
[documentation](https://github.com/silverstripe/silverstripe-docsviewer/tree/master/docs/en)).
|
||||
|
||||
## Syntax
|
||||
|
||||
### Relative Links
|
||||
|
||||
Relative links can point to other markdown pages in the same module.
|
||||
They are always referred to **without** the `.md` file extension.
|
||||
"Absolute" links relate to the root of a certain module,
|
||||
not the webroot of the renderer project or the filesystem root.
|
||||
|
||||
* link to folder on same level: `[title](sibling/)`
|
||||
* link to page on same level: `[title](sibling)`
|
||||
* link to parent folder: `[title](../parent/)`
|
||||
* link to page in parent folder: `[title](../parent/page)`
|
||||
* link to root folder: `[title](/)`
|
||||
* link to root page: `[title](/rootpage)`
|
||||
|
||||
Don't forget the trailing slash for directory links,
|
||||
it is important to distinguish files from directories.
|
||||
|
||||
<div class="notice" markdown='1'>
|
||||
It is recommended to use absolute links over relative links
|
||||
to make files easier to move around without changing all links.
|
||||
</div>
|
||||
|
||||
### API Links
|
||||
|
||||
You can link to API documentation from within the markup by pseudo-links.
|
||||
These are automatically resolved to the right URL on `http://api.silverstripe.org`.
|
||||
API links are automatically wrapped in `<code>` blocks by the formatter.
|
||||
|
||||
* Link to class: `[api:DataObject]`
|
||||
* Link to static method: `[api:DataObject::has_one()]`
|
||||
* Link to instance method: `[api:DataObject->write()]`
|
||||
* Link to static property: `[api:DataObject::$searchable_fields]`
|
||||
* Link to instance property: `[api:DataObject->changedFields]`
|
||||
* Custom titles: `[my title](api:DataObject)`
|
||||
|
||||
There's some gotchas:
|
||||
|
||||
* This notation can't be used in code blocks.
|
||||
* If you want to use API links to other modules or versions of the same module, you'll have to use the full `http://` URL.
|
||||
* You can't mark API links in backticks to trigger `<pre>` formatting, as it will stop the link parsing.
|
||||
The backticks are automatically added by the parser.
|
||||
|
||||
### Code Blocks with Highlighting
|
||||
|
||||
Code blocks can optionally contain language hints that a syntax highlighter can
|
||||
pick up. Use the first line in the block to add a language identifier, prefixed by three colons (`:::`), for example `:::php`.
|
||||
We're currently using the [syntaxhighlighter](http://code.google.com/p/syntaxhighlighter/) JavaScript implementation.
|
||||
See a [list of supported languages](http://code.google.com/p/syntaxhighlighter/wiki/Languages).
|
||||
|
||||
Example for PHP:
|
||||
|
||||
:::php
|
||||
class Page extends SiteTree {
|
||||
public function myFunction() {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
||||
For SilverStripe templates, please use `:::ss` as a brush.
|
||||
|
||||
### Images
|
||||
|
||||
As a convention, referenced images in a Markdown formatted page should always be stored
|
||||
in an `_images/` folder on the same level as the page itself. Try to keep the image size
|
||||
small, as we typically package the documentation with the source code download, and
|
||||
need to keep the file size small.
|
||||
|
||||
You can link to absolute image URLs as well, of course.
|
||||
|
||||
## FAQs
|
||||
|
||||
### How do I preview my own SS Markdown?
|
||||
|
||||
Thats only possible with the `docsviewer` module - we don't have a standalone parser.
|
||||
|
||||
### Can I run my own documentation server?
|
||||
|
||||
Yes, the `docsviewer` module just requires a default SilverStripe installation (2.4+).
|
||||
|
||||
### Can I generate SS Markdown other formats?
|
||||
|
||||
Currently this is not supported, as all HTML is generated on the fly.
|
||||
|
||||
### Can I contribute to the parser and rendering project?
|
||||
|
||||
Of course, the `docsviewer` code is BSD licensed - we're looking forward to your contributions!
|
||||
|
||||
## Related ##
|
||||
|
||||
* [contributing/documentation](contributing/documentation): The doc.silverstripe.org website has certain styling and writing conventions
|
||||
Loading…
Reference in New Issue