# Documentation macros (in AsciiDoctor, PHP and Wordpress shortcodes) to easily make links to API docs and embed images

**URL:** <https://forum.castle-engine.io/t/documentation-macros-in-asciidoctor-php-and-wordpress-shortcodes-to-easily-make-links-to-api-docs-and-embed-images/495>\
**Category:** News\
**Created:** [January 8, 2022, 6:05pm UTC](https://forum.castle-engine.io/t/documentation-macros-in-asciidoctor-php-and-wordpress-shortcodes-to-easily-make-links-to-api-docs-and-embed-images/495 "2022-01-08T18:05:03Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![michalis](https://forum.castle-engine.io/user_avatar/forum.castle-engine.io/michalis/32/3_2.png) [@michalis](https://forum.castle-engine.io/u/michalis)\
**Post date:** [January 8, 2022, 6:05pm UTC](https://forum.castle-engine.io/t/documentation-macros-in-asciidoctor-php-and-wordpress-shortcodes-to-easily-make-links-to-api-docs-and-embed-images/495/1 "2022-01-08T18:05:03Z")

</div>

| [![Upcoming viewport manual](https://castle-engine.io/wp/wp-content/uploads/2022/01/Zrzut-ekranu-z-2022-01-08-01-53-17-200x136.png)](https://castle-engine.io/wp/wp-content/uploads/2022/01/Zrzut-ekranu-z-2022-01-08-01-53-17.png "Upcoming viewport manual") |

Writing engine documentation is so much easier now! _In progress:_ I’m writing important new manual chapters about using viewport within the editor. It is really easier now with AsciiDoctor + macros I describe below, the improvements to our website infrastructure were absolutely worth it.

Following my [plans](https://castle-engine.io/wp/2021/12/31/many-documentation-upgrades-using-asciidoctor-as-our-primary-way-to-write-documentation-michalis-thoughts-and-plans-about-our-documentation/), I have addressed 2 _“pain points”_ of writing documentation: easily linking to API docs and embedding images. Now in AsciiDoctor you can use macros `cgeref`, `cgeimg` to easily add a reference / images. Sample of usage:

```
References to API docs:
```

- cgeref:TCastleScene[]
- cgeref:ApplicationProperties[]

// You don’t need to care in which unit they are defined.  
// You don’t need to care how PasDoc generates link to them  
// (using anchors, like for procedures, or special pages, like for classes).  
// Uses new PasDoc PHP output.

Some images:

cgeimg::block[aaa.png|Description of AAA]  
cgeimg::float[dragon\_0\_wire.png|Dragon,gamma\_nogamma\_helmet.png|Gamma Correction]  
cgeimg::float[  
dragon\_0\_wire.png|Dragon,  
gamma\_nogamma\_helmet.png|Gamma Correction  
]

// The thumbnails will be auto-generated.  
// The syntax is short, and just exposes the 2 image layouts we need:  
// on the side, or within the main content flow.

I wrote extensive documentation of them in [cge-www README](https://github.com/castle-engine/cge-www).

Analogous PHP functions `cgeref`, `cgeimg` can be used in PHP.

Analogous WordPress shortcodes `cgeref`, `cgeimg` can be used for WordPress news posts.

Future:

- We’ll keep the current separation of WordPress vs AsciiDoctor for some time. This works nicely: _Use WordPress for news, use AsciiDoctor for non-news_. AsciiDoctor is better for version control and grepping. WordPress is better for auto-sending to other social platforms. Maybe a different resolution of this will come one day, for now the current situation actually addresses all needs (for news and non-news) best.

- The PHP way of writing docs is obsolete. With time, we will migrate all or almost-all of our documentation to AsciiDoctor (I already wrote some EmacsLisp helpers that I’m using for this). I suspect some exceptions (like main page) may remain custom-coded in PHP, but these will be exceptions.