mirror of
https://github.com/silverstripe/silverstripe-docsviewer
synced 2024-10-22 11:05:56 +02:00
43b6d42719
This major update changes the behaviour of the docviewer module to use a cached manifest rather than on demand. This allows us to simplify the URL matching and store 'nice' URL configuration rather than altering handleAction().
116 lines
4.7 KiB
Markdown
116 lines
4.7 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 [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 |