mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-06 09:41:36 +02:00
113 lines
4.6 KiB
Markdown
113 lines
4.6 KiB
Markdown
|
# 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 [sapphiredocs](http://open.silverstripe.org/browser/modules/sapphiredocs/trunk)
|
||
|
module installed (see module [README](http://open.silverstripe.org/browser/modules/sapphiredocs/trunk/README.md) and
|
||
|
[documentation](http://open.silverstripe.org/browser/modules/sapphiredocs/trunk/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.
|
||
|
|
||
|
Note: It is recommended to use absolute links over relative links
|
||
|
to make files easier to move around without changing all links.
|
||
|
|
||
|
### 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 {
|
||
|
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 `sapphiredocs` module - we don't have a standalone parser.
|
||
|
|
||
|
### Can I run my own documentation server?
|
||
|
|
||
|
Yes, the `sapphiredocs` 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 `sapphiredocs` code is BSD licensed - we're looking forward to your contributions!
|
||
|
|
||
|
## Related ##
|
||
|
|
||
|
* [contributing](contributing#writing-documentation): The doc.silverstripe.org website has certain styling and writing conventions
|