📰 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

you have to create a Notion integration here.
since we’re not writing to Notion, at this time only read access is necessary
grab the notion_token, something like secret_xxxxxxxxxx
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

create an AWS S3 bucket
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:

HTML with $page→toHtml()
MarkDown with $page→toMd()
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

Out of Scope

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

beco/mirror