Markdown has limited formatting capabilities. dCard allows you to declare a card name and parameters in body text, which everkm-publish renders into HTML using theme templates. Site-level cards are stored in __everkm/extend/dcard/.
Inline Syntax (Recommended)
When a card needs no additional parameters, you can write inline code on its own line in the body text:
`dcard/download`
This is equivalent to inserting the download card during rendering, without needing a YAML/JSON code block. Card names only allow letters, digits, underscores, and hyphens (a-zA-Z0-9_-).
The inline syntax requires the line to contain only `dcard/card-name`, with no other text before or after.
Code Block Syntax
Enter the following in a Markdown file:
```yaml dcard/bilibili vid: video_id ```
The above snippet declares the use of the bilibili dcard. The format follows code block syntax, but the context parameter format only supports json and yaml. The content is passed as template parameters when rendering the dcard template.
The dcard template filename is <dcard_name>.dcard.html, and the manifest filename is <dcard_name>.dcard.yaml.
Resources for the same dcard must be placed in the same directory.
Theme-native dcard files are stored in any subdirectory under the templates directory; site-level dcard files are stored in __everkm/extend/dcard/ (since v0.17.2; the old path __dcard is deprecated).
Referencing Resource Files
In most cases, dcard context static content is sufficient. However, in special scenarios, such as referencing an audio file in the current directory, special handling is needed. Otherwise, the referenced resource will not be packaged during publishing. Therefore, everkm-publish supports using standard template tags in dcard context, making the context more powerful.
For example, suppose we want to render an audio player. If the template already provides an audio dcard, we need to specify the audio file address via the media parameter.
We also want the referenced audio file to be automatically exported during publish and have its URL converted for the published site.
We can use the media function for this. Code below — note the use of quotes:
```yaml dcard/audio
media: "{{media(text='002 Home.mp3')}}"
```
Since referencing resource files in dcard is a common operation, everkm-publish provides a syntax sugar equivalent to the above:
```yaml dcard/audio media: "$media:002 Home.mp3" ```
Using the $media: prefix before a file path will automatically resolve it to the corresponding template during processing.
File paths can use absolute or relative paths.
Manifest Configuration
Each dCard requires a *.dcard.yaml manifest file that declares the JS and CSS resources to inject into the page.
# JavaScript files to inject into the page, optional
js:
- assets/a.js
# Stylesheets to inject into the page, optional
css:
- assets/b.css
The card name is automatically extracted from the manifest filename, without needing to declare it in the file. For example, the card name of bilibili.dcard.yaml is bilibili.
Resource paths must use relative paths based on the manifest's directory. The assets/ subdirectory in the same directory as the manifest is automatically synced to dist/assets/dcard-{card-name}/ during rendering, without additional declarations.
Injection behavior:
- Files in
css→ generate<link rel="stylesheet">tags, injected into<head> - Files in
js→ generate<script src="">tags, injected before</body>
Example (complete directory structure for the bilibili card):
extend/dcard/bilibili/
bilibili.dcard.yaml # manifest
bilibili.dcard.html # card Tera template
assets/
bilibili.js
bilibili.css
name, js, and css are the currently supported manifest fields. The legacy assets.inject / assets.files structure is no longer used.