|
| 1 | +# AstroNot |
| 2 | + |
| 3 | +AstroNot is a fully customizable site builder powered by Astro & Notion. |
| 4 | + |
| 5 | +Write, Edit, and Publish directly from Notion with total control over the website and design! |
| 6 | + |
| 7 | +## 🙋🏼 Why AstroNot? |
| 8 | + |
| 9 | +There are plenty of good options for turning your Notion content into a website, such as `super.so`. Why AstroNot? |
| 10 | + |
| 11 | +First of all, AstroNot is 100% open-source and free. You can self host on a variety of platforms, such Vercel and Netlify, or for free on Github Pages. `super.so`, is $16/month _(without analytics)_! |
| 12 | + |
| 13 | +Other popular Notion site builders allow for some limited customization such as changing fonts and logos, but are inherently based on Notion's layout; this is great if you want to design your entire site in Notion and mirror it to the web! However, if you want to design your own site with full control while still using Notion as a Content Management Solution for content such as blog posts and articles, that's where AstroNot shines! |
| 14 | + |
| 15 | +AstroNot exports Notion content into MarkdownX, which can be styled and customized however you like. Since AstroNot only syncs Notion content to the `/posts` route, the entire website is available to modify, including the HTML, styling, and scripts. |
| 16 | + |
| 17 | +AstroNot is built for performance from the ground up. Images are fetched and optimized at build time, resulting in page loads much faster than the native Notion pages! AstroNot also supports Chrome's new `View Transitions` API, resulting in smooth navigation transitions and page animations in supported environments. |
| 18 | + |
| 19 | +Use the included Flowbite UI or Svelte components to design a landing page, marketing site, or portfolio. Or, feel free to BYOF _(Bring Your Own Framework)_ and add your own React or Vue components. The sky is the limit! |
| 20 | + |
| 21 | +## 📡 Technology |
| 22 | + |
| 23 | +Space requires **FAST** speeds, so AstroNot is built for performance with the **FAST** stack: |
| 24 | + |
| 25 | +- **Flowbite**: Flowbite is a UI Framework which is built on top of Tailwind CSS. It's a collection of design elements, components, and layouts, helping to build pixel-perfect responsive websites and apps faster and easier. Flowbite can be used with all of the popular frameworks (React, Svelte, Vue, etc), or with no framework at all. |
| 26 | + |
| 27 | +- **Astro**: Astro builds fast content sites, powerful web applications, dynamic server APIs, and everything in-between; pages are pre-rendered on the server so adding extra frameworks and large libraries will only slow users if hydrated to client for interactivity (using `client:load`, etc). AstroNot is built on Astro v3, which offers a host of new powerful features including `View Transitions` and enhanced `Image Optimization`. |
| 28 | + |
| 29 | +- **Svelte**: Svelte describes itself as "cybernetically enhanced web apps". Svelte is not just a front-end UI framework, but also a compiler - which means that deployed web applications can remain lightweight and fast, without large Javascript bundle sizes required of other frameworks such as React. Svelte pairs perfectly with Astro and `nanostores`. |
| 30 | + |
| 31 | +- **Tailwind**: Tailwind is utility-first CSS framework packed with classes like `flex`, `pt-4`, `text-center` and `rotate-90` that can be composed to build any design, directly in your markup. Tailwind used to power all of the Flowbite components included in AstroNot, as well as many other available Tailwind based UI libraries (such as TailwindUI) that are also compatible out of the box with AstroNot. |
| 32 | + |
| 33 | +### 📦 Package Manager |
| 34 | + |
| 35 | +AstroNot includes `pnpm` out of the box, and supports `bun`! Feel free to replace with your favorite package manager of choice. |
| 36 | + |
| 37 | +### 🎨 Animations |
| 38 | + |
| 39 | +- Includes Tailwind Animated library out of the box: [https://www.tailwindcss-animated.com/](https://www.tailwindcss-animated.com/) |
| 40 | + - Just add classes such as `wiggle`, `rotate-x`, `jump-out`, `bounce`, `fade-left`, or `flip-down`. |
| 41 | +- Svelte animations: [https://svelte.dev/docs/svelte-animate](https://svelte.dev/docs/svelte-animate) |
| 42 | +- View Transition support via Astro. Use `transition:name` to animate elements between page loads. |
| 43 | + |
| 44 | +### ↝ MarkdownX processing |
| 45 | + |
| 46 | +- Uses `notion-to-md` under the hood for converting Notion to Markdown |
| 47 | +- `/src/notion.js` contains the Notion sync and transform code. Perform any alterations to Post layout and logic in this file. |
| 48 | + |
| 49 | +## 👏🏼 Notion Features |
| 50 | + |
| 51 | +- Tag support: Syncs tags with your posts, including color! |
| 52 | +- Automatically generate Table of Content based on document. Supports nested headings. |
| 53 | +- Images optimized based on view resolution at build time. High resolution images will be converted to the best format and size for the layout. |
| 54 | + |
| 55 | +## ⚙️ Notion Setup |
| 56 | + |
| 57 | +- Get your API key here |
| 58 | + |
| 59 | +## 🚀 Installation |
| 60 | + |
| 61 | +- Clone this repo |
| 62 | +- Install with your package manager of choice _(`pnpm`, `bun`, etc...)_: `pnpm install` |
| 63 | +- Move `.env.example` to `.env` and add your Notion API key and database ID |
| 64 | +- Run `pnpm sync` to sync Notion Content for the first time |
| 65 | +- Run `pnpm dev` to start development server |
| 66 | +- Remove any unwanted components, such as `HyperDark` from `components/`, and `pages/` folder. |
| 67 | + |
| 68 | + - All of the built-in content here is available for reference, but can be modified or deleted |
| 69 | + - Parallax components show how to add interactive svelte components |
| 70 | + - `DarkMode` and `Hyperdark` components demonstrate how to use `nanostores` for data peristence with `Svelte` |
| 71 | + - Various examples using different Astro hydration techniques, such as `client:load`, `client:visible`, and `client:idle`. |
| 72 | + - _Soon, a `starter` branch will be available with barebones setup to get started quickly_ |
| 73 | + |
| 74 | +- Replace with your own content and design! |
| 75 | + |
| 76 | +## 🏗️ Project Structure |
| 77 | + |
| 78 | +```text |
| 79 | +/ |
| 80 | +├── public/ |
| 81 | +├── src/ |
| 82 | +│ └── pages/ |
| 83 | +│ └── posts/ <-- Notion content lives here |
| 84 | +│ ├── components/ |
| 85 | +│ ├── layouts/ |
| 86 | +│ │ └── Layout.svelte |
| 87 | +│ │ └── PostLayout.svelte |
| 88 | +│ │ └── _DarkMode.svelte |
| 89 | +│ │ └── _Header.svelte |
| 90 | +│ │ └── _Footer.svelte |
| 91 | +└── package.json |
| 92 | +``` |
| 93 | + |
| 94 | +AstroNot looks for `.astro`, `.md.` or `.mdx` files in the `src/pages/` directory. Each page is exposed as a route based on its file or folder name. A page can be one `.astro` file, or a folder containing many components; if using a subfolder inside `/pages` or `layout`, all component filenames must be prefixed `_`, such as `/pages/home/_Features.[astro,svelte,jsx,etc...]` and the main file should be called `index.astro`. |
| 95 | + |
| 96 | +There's nothing special about `src/components/`, but that's where we like to put any Astro or React/Vue/Svelte/Preact components. It's recommended to use this location if sharing components. |
| 97 | + |
| 98 | +Any static assets, like images, can be placed in the `public/` directory. Images which are to be optimized need to be placed inside `/src/images`, as they need to be imported during Astro's build process. |
| 99 | + |
| 100 | +## 🧞 Commands |
| 101 | + |
| 102 | +All commands are run from the root of the project, from a terminal: |
| 103 | + |
| 104 | +| Command | Action | |
| 105 | +| :------------------------ | :---------------------------------------------------- | |
| 106 | +| `npm install` | Installs dependencies | |
| 107 | +| `npm run dev` | Starts local dev server at `localhost:4321` | |
| 108 | +| `npm run build` | Build your production site to `./dist/` | |
| 109 | +| `npm run preview` | Preview your build locally, before deploying | |
| 110 | +| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | |
| 111 | +| `npm run astro -- --help` | Get help using the Astro CLI | |
| 112 | +| **`npm run sync`** | **Download & Transform Notion content into `/posts`** | |
| 113 | + |
| 114 | +## 🔄 Automatic Publish Deploys |
| 115 | + |
| 116 | +You can use webhooks or automated platforms such as `Make` or `Zapier` to automatically trigger deploys on compatible platforms such as `Netlify`. |
| 117 | + |
| 118 | +[make.com](https://make.com/) currently offers 1,000 operations / month, which is more than enough for most use cases to automate publishing for a small blog. To enable, simply connect Make to Notion and watch for any changes to your content database, and connect to trigger Netlify deploy action (which will automatically build a new site based off of the latest content from Notion); this can be set up to run as often as every 15 minutes. |
| 119 | + |
| 120 | +- [ ] TODO: Add Video |
0 commit comments