search

souvikinator / notion-to-md

Convert notion pages, block and list of blocks to markdown (supports nesting and custom parsing)
https://www.npmjs.com/package/notion-to-md
MIT License
1.11k stars 91 forks source link

feature: handle properties as frontmatter #26

Closed parkuman closed 2 years ago

parkuman commented 2 years ago

Hey everyone!

I thought it would be an interesting feature to allow notion-to-md to take properties of a page and convert them to YAML-style markdown frontmatter. For example:

A notion page with the following properties:

image

would get converted to the following markdown:

---
title: Second Post
summary: My second blog post, its really good and cool
slug: second-post
author: Parker Rowe
date: 2022-03-11
tags:
 - TypeScript
 - SvelteKit
 - Markdown
---

# My Second Post

Yea baby

...

I've started working on a similar parser for my personal site using Notion as my blog CMS (example WIP code here), but I thought it could be useful to have it baked into notion-to-md.

Feel free to discuss! 🍻

souvikinator commented 2 years ago

Hey Parker, thanks for the suggestion Definitely, this feature can be included however I'm not sure if this is within the scope of this package. The package's focus is to convert notion pages to markdown. Here we have to convert properties to YAML and then concatenate it with the markdown of the page. I did go through your code and it seems to work.

I see a lot of CMS-based projects are using this package so I understand how handy this feature will be therefore I don't mind adding it. It has to be a separate method rather than adding it to the existing methods.

I do have a few things in mind related to this so, let me know if you are interested. We can discuss the approach and possible use cases.

parkuman commented 2 years ago

Hey!

Completely understandable. Implementing it as a different method would be quite useful so the feature could be entirely opt-in if the developer wants to use it.

I think it would be cool to have as a part of the package and I'd be glad to help. Would love to hear some of your ideas on this topic too :)

souvikinator commented 2 years ago

Awesome. Let's work on a basic version. Breaking it down:

  1. A private method that takes page properties/page id and converts it to a simplified object
  2. A public method that uses the private method and converts the object to a YAML string.

if you have any other approaches or questions in mind then feel free to share.

emoriarty commented 2 years ago

Hey guys,

I've worked on the same feature for the ruby package. Basically, I've taken the same approach as you mention @parkuman. The Front matter is optional.

Anyway, I'm leaving the comment here so perhaps what has been done in notion_to_md can help you. The front matter is parsed here.

Cheers!

parkuman commented 2 years ago

@emoriarty Nice! I really like the conversion to snake case even if its not like that already. Thank you for sharing that.

@souvikinator the two staged approach could definitely work well. Seems like frontmatter is commonly used as JSON, TOML (but more often than not), YAML: https://gohugo.io/content-management/front-matter/ . We could allow the user to choose the outputted language for frontmatter, but for now just YAML would be perfect.

So some other questions I thought of:

I guess the main question is do we want to include all information from each and convert it to YAML? Or only pick and choose the more useful ones like @emoriarty and I have been doing. If there's no preference then I could get started on one that just includes all the information and go from there :) The Type definitions from the notion package shows them all, i think this is where they are: https://github.com/makenotion/notion-sdk-js/blob/main/src/api-endpoints.ts

souvikinator commented 2 years ago

True, we can go with YAML for now and later allow users to pass a parameter mentioning the language.

Do we include the default id, title, created_time, last_edited_time, icon, archived and cover parameters from notion in the front matter?

The requirement varies from person to person so probably we have to make it in a way users can remove unnecessary properties.

Possible flow:

or 

options={
  language?: "",
  remove?: [ fields_to_remove... ]
}

for fields like icon and cover, we can include only the image URL.

for notions Date parameter, it is returned as an object. There's the normal start_date and optional end_date parameter. We would need to make a decision on including all info or not.

start_date should do the work.

for Multi-Select (each one is an object that contains text + color information). I'm using the color information on my blog site right now but that is definitely overkill.

Great work! however, I'm not sure if the color thing is supported in Hugo and other popular static site generators, so for the time being we can keep the plain_text only.

same goes for the person parameter, it is returned as a list of people and each one is an object that contains profile pic info, name & more

let's just extract the name for now.

Would love to hear your thoughts on this.

souvikinator commented 2 years ago

Hello there, I'm closing this issue as it is out of the scope for the package. The package's focus is to convert notion pages to markdown only.

augnustin commented 1 year ago

Hey,

@souvikinator I don't really agree with you about this feature not being in the scope of the package. The point here is to facilitate using notion as a CMS using standard formats and clearly markdown with frontmatter is part of it.

I'll go for my own custom implementation and will report it here in case it helps others, maybe we could discuss about making this core later.