README

A PHP way to read Notion pages and (optionally) upload images and videos to an S3 bucket (and link accordingly).

This is my first package distributed through composer, bare with me.

Operation

Prepare Services

Notion

1. you have to create a Notion integration here.
2. since we’re not writing to Notion, at this time only read access is necessary
3. grab the notion_token, something like secret_xxxxxxxxxx
4. on every page you want to be read by this script, you need to share it with the integration as shown in the image, quite easy part but tricky to find

my Notion integration is called page mirror, use your own, the one created on the first step ☝️

S3

1. create an AWS S3 bucket
2. grab the AWS_KEY, AWS_SECRET, AWS_REGION and BUCKET_NAME Note that by default, images will be uploading using the following structure: s3.AWS_REGION.amazonaws.com/BUCKET_NAME/PAGE_ID/public/image/IMAGE_ID.jpg

CLI Invocation

You have to create a $config object with the previously created services’ access variables as follows:

$config = [
  'notion_token' => 'NOTION_TOKEN',
  'aws_key'      => 'AWS_KEY',
  'aws_secret'   => 'AWS_SECRET',
  'aws_region'   => 'AWS_REGION',
  'bucket_name'  => 'BUCKET_NAME',
];

You now can invoke the Notion object.

$notion = new \b3co\notion\Notion($config);
$page   = $notion->getPage(PAGE_ID);
echo $page->toHtml();

Yii Invocation

First, on the config file either web.php or console.php add

$config = [
	...
	'components' => [
		...
		'notion' => [
			'class' => 'b3co\notion\YiiNotion',
		  'config' => [
		    'notion_token' => getenv('notion_token'),
		    'aws_key'      => getenv('aws_key'),
		    'aws_secret'   => getenv('aws_secret'),
		    'bucket_name'  => getenv('aws_bucket'),
		    'aws_region'   => getenv('aws_region'),
		  ]
		],
		...
  ]
	...
];

Second, use the YiiNotion object to get a Notion object and execute accordingly.

class NotionController extends Controller {

  public function actionIndex($id) {
    define('VERBOSE', false);
    $notion = Yii::$app->get('notion')->getNotion();
    $page = $notion->getPage($id);
    echo $page->toHtml();

    return ExitCode::OK;
  }
}

Templates (work in progress)

By default, three different export templates are set to each object:

1. HTML with $page→toHtml()
2. MarkDown with $page→toMd()
3. Plain text with $page→toString()

Template families

Optionally you can use the template factory and create a template family under $config->templates_dir/TEMPLATE_FAMILY/ so if you invoke $page->toTemplate(TEMPLATE_FAMILY)
system will check for each block type template there, named as BLOCK_TYPE.template. For instance, for a template family called basic, you’ll have:

Where image and page are block types.

Each template can use any given format/language and use objects’ attributes to be printed like [:ATTRIBUTE], for example an image with url and caption.

<div><img src='[:url]'>
  <div>[:caption]</div>
</div>

A complete list of objects and attributes is available here.

Important 🚨: If a template file is not found, that block will not be processed.

A note on toHtml method

HTML templating can be overwritten by creating a template family called html, if a block item template is found, will be used, if not, fail back will use the hardcoded HTML template.

Notion Objects

Supported Objects List

• Paragraph blocks
• Heading one blocks
• Heading two blocks
• Heading three blocks
• Image blocks
• To do blocks
• Column List and Column Blocks
• Quote blocks
• Bulleted list item blocks
• Code blocks
• Toggle blocks
• Divider blocks
• Video blocks
• Numbered list item blocks (tricky, work in progress)
• Embed blocks
• Equation blocks
• Table row blocks
• Table blocks
• Callout blocks
• Child page blocks

Out of Scope

• Child database blocks
• File blocks
• PDF blocks
• Bookmark blocks
• Table of contents blocks
• Breadcrumb blocks
• Link Preview blocks
• Template blocks
• Link to page blocks
• Synced Block blocks

This very README file is created and stored in Notion and converted to MD using this script, last update 2022-08-24 → .