Read this post in 中文 or 日本語.

Hey HackMD Community,

We have some exciting news to share with you! At HackMD, we're always striving to enhance your experience and provide you with advanced features. As part of this commitment, we'll be introducing breaking changes to how metadata, essentially titles and tags, are handled in your notes. We understand that this might cause some initial confusion, but we're here to guide you through it and help you adapt smoothly.

Why the change?

Previously, metadata was stored within the note itself. This approach had a few downsides, such as every metadata change altering the note itself and triggering unnecessary notifications.

We've listened to your feedback and are making these changes to address those issues and to introduce features like batch edit metadata for multiple notes. These also bring us closer to the more exciting new features, such as backlinks.

What are the changes?

• Metadata will be stored in HackMD, not within the notes themselves.
• There are fields in the editor for editing the title and tags.
• Metadata other than the title and tags can be set in the "Settings" of the notes.
• Themes and other settings for Slide mode can be set in the "Slide mode" of the "Share" menu.

Migration policies to minimize impact

To minimize disruption, we have implemented migration policies to derive default values for the new metadata. However, please note that some glitches may occur due to these policies. Let's take a closer look at how they will work:

Title migration

• If a title is set in the YAML frontmatter, it will be taken as the new title of the note.
• If no title is set in the YAML frontmatter but there is at least one H1 header in the note, the first H1 header will become the new note title.
• If no title is set in the YAML frontmatter and there are no H1 headers in the note, the note will be titled as "Untitled."

Tags migration

• If tags are set in the YAML frontmatter, they will be taken as the new tags for the note.
• If tags are not set in the YAML frontmatter but are set using H6 headers, those set with H6 headers will be considered as the new tags for the note.
• If no tags are found in either the YAML frontmatter or H6 headers, the note will not have any tags.

Metadata other than the title and tags

The rest of the metadata will be migrated as it is.

Suggestions to mitigate the "weirdness"

We understand that during the transition, you may encounter some peculiarities in how your notes are rendered. Here are a few suggestions to help you navigate these changes smoothly:

1. Handling duplicated titles

If your note had a title set using the H1 header, you may notice duplicate strings both in the new title field and within the note where the H1 is located.

Although in this case we collapse the title and tags in view mode to prevent visitors from feeling stupid, we recommend that you manually remove the H1 header used for the title to avoid any redundancy.

2. Managing H6 tags

H6 tags used to be rendered in the View mode, and we will continue to support that. However, any new edits to the H6 tags will not take effect.

To add or remove tags, we recommend using the tag field or from the note list (under development and will ship soon), where you can conveniently edit tags for multiple notes at once.

Since there is a place for tags in View mode, and H6 tag headers are also rendered, the latter may be redundant and you may want to remove them.

We're here to help 🙌

We understand that adjusting to these changes may take some time, and our support team is here to assist you every step of the way. If you have any questions, concerns, or need further guidance, please reach out to us through our support channels (email、Discord), and we'll be more than happy to assist you.

We appreciate your understanding and patience during this transitional period. These changes will pave the way for exciting new possibilities and improved functionality within HackMD.

Thank you for being a valued member of our community and for your continued support as we evolve together.

Happy writing!

The HackMD Team