diff --git a/src/check-project/readme/api-docs.js b/src/check-project/readme/api-docs.js
index e56421d32..2eaf22885 100644
--- a/src/check-project/readme/api-docs.js
+++ b/src/check-project/readme/api-docs.js
@@ -13,7 +13,7 @@ export const APIDOCS = (pkg, parentManifest) => {
   const ghPages = parseGhPagesUrl(pkg, parentManifest)
 
   return `
-## API Docs
+# API Docs
 
 * [${ghPages}](${ghPages})
 `
diff --git a/src/check-project/readme/install.js b/src/check-project/readme/install.js
index a4a4cb7e1..da0d73428 100644
--- a/src/check-project/readme/install.js
+++ b/src/check-project/readme/install.js
@@ -8,7 +8,7 @@ export const INSTALL = (pkg) => {
   }
 
   const nodeInstall = `
-## Install
+# Install
 
 \`\`\`console
 $ npm i ${pkg.name}
diff --git a/src/check-project/readme/license.js b/src/check-project/readme/license.js
index 5d7a4c1eb..1a5adf233 100644
--- a/src/check-project/readme/license.js
+++ b/src/check-project/readme/license.js
@@ -3,14 +3,14 @@
  */
 const licenses = {
   ipfs: (repoOwner, repoName, defaultBranch) => `
-## License
+# License
 
 Licensed under either of
 
   * Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / http://www.apache.org/licenses/LICENSE-2.0)
   * MIT ([LICENSE-MIT](LICENSE-MIT) / http://opensource.org/licenses/MIT)
 
-## Contribute
+# Contribute
 
 Contributions welcome! Please check out [the issues](https://github.com/${repoOwner}/${repoName}/issues).
 
@@ -23,14 +23,14 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
 `,
   default: (repoOwner, repoName, defaultBranch) => `
-## License
+# License
 
 Licensed under either of
 
   * Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / http://www.apache.org/licenses/LICENSE-2.0)
   * MIT ([LICENSE-MIT](LICENSE-MIT) / http://opensource.org/licenses/MIT)
 
-## Contribution
+# Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
 `
diff --git a/src/check-project/readme/structure.js b/src/check-project/readme/structure.js
index 2525ebc0c..48522335e 100644
--- a/src/check-project/readme/structure.js
+++ b/src/check-project/readme/structure.js
@@ -18,7 +18,7 @@ export const STRUCTURE = (monorepoDir, projectDirs) => {
   }
 
   return `
-## Packages
+# Packages
 
 ${Object.entries(packages).map(([key, value]) => {
   return `* [\`${key}\`](.${key}) ${value}`
diff --git a/src/docs/readme-updater-plugin.js b/src/docs/readme-updater-plugin.js
index 03a4ed754..def2bc616 100644
--- a/src/docs/readme-updater-plugin.js
+++ b/src/docs/readme-updater-plugin.js
@@ -73,7 +73,7 @@ export function load (app) {
  */
 function updateModule (comment, manifestPath, readmePath, app) {
   const about = `
-## About
+# About
 
 ${
   comment.summary
@@ -85,7 +85,7 @@ ${
         .map(item => {
           if (item.tag === '@example') {
             return `
-### Example
+## Example
 
 ${
   item.content