diff --git a/.gitignore b/.gitignore
index 8860ce97f..b0408bb9b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,4 +21,5 @@ yarn-error.log*
 
 defang
 samples
-/static/samples-v2.json
\ No newline at end of file
+/docs/samples.md
+/static/samples-v2.json
diff --git a/package.json b/package.json
index 843722df2..d6bc40a35 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
+    "prestart": "./scripts/prebuild.sh",
     "start": "docusaurus start",
     "prebuild": "./scripts/prebuild.sh",
     "build": "docusaurus build",
diff --git a/scripts/prep-samples.js b/scripts/prep-samples.js
index f6db5cf75..6b4777e75 100644
--- a/scripts/prep-samples.js
+++ b/scripts/prep-samples.js
@@ -3,6 +3,7 @@ const path = require('path');
 const YAML = require('yaml');
 
 const samplesDir = process.argv[2];
+let samplesMdContent = ''
 
 // Inspired by https://github.com/compose-spec/compose-go/blob/main/template/template.go
 const interpolationRegex =
@@ -23,6 +24,12 @@ directories.forEach((sample) => {
     let readme;
     try {
         readme = fs.readFileSync(path.join(samplesDir, sample, 'README.md'), 'utf8');
+        // replace the text after the first `#` with a link to the sample
+        // readme = readme.replace(/^# (.*)/, `# [$1](https://github.com/DefangLabs/samples/tree/main/samples/${sample})`);
+        readme = readme.replace(/^# (.*)/, (match, p1) => {
+            return `# [${p1}](https://github.com/DefangLabs/samples/tree/main/samples/${sample})`;
+        });
+        samplesMdContent += readme + "\n\n";
     } catch (error) {
         readme = `# ${sample}`;
     }
@@ -34,10 +41,16 @@ directories.forEach((sample) => {
     // Languages:
     //
     // We want to extract the title, short description, tags, and languages from the readme. Tags and languages are comma separated lists.
-    const title = readme.match(/Title: (.*)/)[1];
-    const shortDescription = readme.match(/Short Description: (.*)/)[1];
-    const tags = readme.match(/Tags: (.*)/)[1].split(',').map(tag => tag.trim());
-    const languages = readme.match(/Languages: (.*)/)[1].split(',').map(language => language.trim());
+    let title, shortDescription, tags, languages;
+    try {
+        title = readme.match(/Title: (.*)/)[1];
+        shortDescription = readme.match(/Short Description: (.*)/)[1];
+        tags = readme.match(/Tags: (.*)/)[1].split(',').map(tag => tag.trim());
+        languages = readme.match(/Languages: (.*)/)[1].split(',').map(language => language.trim());
+    } catch (error) {
+        console.log(`@@ Failed to parse readme for sample ${sample}`, error);
+        return;
+    }
 
     let configs = new Set();
     try {
@@ -96,14 +109,30 @@ directories.forEach((sample) => {
 
 const stringified = JSON.stringify(jsonArray, null, 2);
 
-// fs.writeFileSync(path.join(__dirname, '..', 'samples.json'), stringified);
+// exclude any lines which start with '---'
+samplesMdContent = samplesMdContent.replace(/---.*\n/g, '');
+// exclude any lines which include markdown images `![`
+samplesMdContent = samplesMdContent.replace(/^.*!\[.*\]\(.*\).*\n?/gm, '');
 
-// we're going to open up the ../docs/samples.md file and replce [] with the stringified JSON
+// increase the header level of all headers in the markdown content
+samplesMdContent = samplesMdContent.replace(/^(#{1,6})\s/gm, (match) => {
+    const headerLevel = match.length - 1; // number of '#' characters
+    const newHeaderLevel = Math.min(headerLevel + 1, 6);
+    return '#'.repeat(newHeaderLevel) + ' ';
+});
 
-// const samplesMd = path.join(__dirname, '..', 'docs', 'samples.md');
-// let samplesMdContents = fs.readFileSync(samplesMd, 'utf8');
-// samplesMdContents += `<Samples samples={${stringified}} />`;
-// fs.writeFileSync(samplesMd, samplesMdContents);
+const frontMatter = `---
+sidebar_class_name: hidden
+title: Samples
+description: A collection of sample applications and configurations for Defang Labs.
+---
+`;
+// prefix samplesMdContent with the front matter
+samplesMdContent = frontMatter + "\n\n" + samplesMdContent;
+
+const samplesMd = path.join(__dirname, '..', 'docs', 'samples.md');
+console.log(`@@ Writing samples markdown to ${samplesMd}`);
+fs.writeFileSync(samplesMd, samplesMdContent);
 
 // save the json to the samples.json file in static
 fs.writeFileSync(path.join(__dirname, '..', 'static', 'samples-v2.json'), stringified);
diff --git a/src/css/custom.css b/src/css/custom.css
index ef198afb5..f116f85b4 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -137,4 +137,8 @@ img.unstyled {
   to {
     background-position: 200% 0;
   }
-}
\ No newline at end of file
+}
+
+.menu__list-item.hidden {
+  display: none;
+}