-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
59 additions
and
324 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,345 +1,66 @@ | ||
| # Blog-Doc | ||
|
|
||
| The Simplest Node.js CMS & SSG!<br /> | ||
| The Simplest Node.js CMS & SSG! | ||
| A tiny flame in the darkness of error... | ||
|
|
||
| > [!IMPORTANT] | ||
| > This documentation no longer represents the diverse features of Blog-Doc. Kindly consult the comprehensive [documentation](https://blog-doc.pages.dev/) for up-to-date information on Blog-Doc's functionalities. | ||
| ## Documentation | ||
|
|
||
| > [!NOTE] | ||
| > Preview of [Blog-Doc's static site demo](https://blogdoc.github.io/). | ||
| With the release of [version 3.0.0](https://github.com/LebCit/blog-doc/releases/tag/v3.0.0), Blog-Doc has undergone some fantastic updates. I've integrated [LiteNode](https://www.npmjs.com/package/litenode) to streamline and enhance your experience. | ||
|
|
||
| ## Motivation & Purpose | ||
| The Blog-Doc admin interface is now more intuitive than ever. Each page comes with its own handy documentation, all designed with [responsive attributes](https://responsive-attributes-generator.pages.dev/) for seamless usability on any device. | ||
|
|
||
| _With all due respect to the time and hard work of every developer who made a Static Site Generator with Node.js, **including the previous versions of Blog-Doc**, those are gasworks!_<br /> | ||
| _I offer my sincerest apologies in advance to each one of these developers, but an app is not supposed to be a gasworks..._<br /> | ||
| **Please read [From 145 to 7 💪](https://lebcit.github.io/posts/from-145-to-7/)**<br /> | ||
| **Also read [The New Blog-Doc](https://blogdoc.github.io/posts/the-new-blog-doc/)** | ||
| You can check out **the full documentation for Blog-Doc** here: [Blog-Doc Documentation](https://blog-doc.pages.dev/). | ||
|
|
||
| ## Requirements | ||
|
|
||
| 1. Blog-Doc works on [Node.js](https://nodejs.org/en) versions greater than 18.x.<br /> | ||
| 1. Use the latest version of each major release. | ||
| 2. The latest version of [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) | ||
| 1. Blog-Doc requires [Node.js](https://nodejs.org/en) version 18.x or higher. | ||
| - For the best experience, use the latest [Long Term Support](https://nodejs.org/en/download/package-manager) (LTS) version. | ||
| 2. Make sure you have the latest version of [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed. | ||
|
|
||
| ## Solid stack of technologies 🪨 | ||
| ## Installation | ||
|
|
||
| ### Backend (input) | ||
| To get Blog-Doc up and running on your machine, follow these steps: | ||
|
|
||
| - Node.js 18.x or higher. | ||
| - [Hono](https://hono.dev/), small, simple, and ultrafast web framework for the Edges. | ||
| - [Eta](https://eta.js.org/), lightweight, powerful, pluggable embedded JS template engine. | ||
| - [Marked](https://marked.js.org/), Markdown parser and compiler. Built for speed. | ||
| 1. Open your preferred IDE (like VS Code) and navigate to the directory where you want to install Blog-Doc. | ||
| 2. In the terminal, you have two options to install Blog-Doc: | ||
|
|
||
| ### Frontend (output) | ||
| ### Option 1: Using `npx` | ||
|
|
||
| - HTML, CSS and a tiny JS file. | ||
|
|
||
| ## Blazing fast and simple 🚀 | ||
|
|
||
| - A zero code configuration static site generator. | ||
| - Ready to use on your Node.js server as a Node.js CMS. | ||
| - Ready to use, after build, as a static site. | ||
| - Without any unnecessary functionalities, loads in a blink of an eye. | ||
| - Easy to install and use. | ||
|
|
||
| ## Design 🎨 | ||
|
|
||
| - Responsive, elegant and simple layout. | ||
| - Ready to use template for blog and/or documentation. | ||
| - Easy to modify if you opt for another design. | ||
|
|
||
| ## Features ⚡ | ||
|
|
||
| - Administrate your app from the front-end!  | ||
| - [Themes](#themes) to change the look and feel of your site!  | ||
| - [Gallery](#the-gallery) to upload your images  | ||
| - Create, Read, Update & Delete your pages and posts  | ||
| - Paginated blog with chosen number of posts per page  | ||
| - Posts pagination to navigate between your posts  | ||
| - Write your content in Markdown  | ||
| - Ability to use HTML in Markdown  | ||
| - Tag(s) for posts  | ||
| - Featured image for posts and pages  | ||
| - Archive route for posts  | ||
| - Tags list route  | ||
| - Individual route for each tag  | ||
| - Titles & Meta Descriptions  | ||
| - Drag and drop your menu links to sort them  | ||
| - [RSS feed](#rss)  | ||
| - [Sitemap](#sitemap)  | ||
| - [Search](#search)  | ||
| - [Code highlighting](#code-highlighting) with highlight.js  | ||
| - [Ids for H2 till H4 in Markdown](#ids-for-h2-till-h4-in-markdown)  | ||
| - No need for hot reloading in development mode  | ||
|
|
||
| ## How to install Blog-Doc? | ||
|
|
||
| Blog-Doc is a `Node.js` app. You should have [Node.js](https://nodejs.org/en/) on your machine.<br /> | ||
| Always go for the **LTS** version. | ||
|
|
||
| If you want to try Blog-Doc, head over it's [Github repository](https://github.com/LebCit/blog-doc) and download it.<br /> | ||
| You can also download it's zip by clicking on the following link: [Blog-Doc ZIP](https://github.com/LebCit/blog-doc/archive/refs/heads/master.zip). | ||
|
|
||
| Once downloaded, extract the zipped folders and files to a new folder and open it in your IDE (I use [VS Code](https://code.visualstudio.com/)). | ||
|
|
||
| Another way is to directly clone the repository itself.<br /> | ||
| Run the following command: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/LebCit/blog-doc.git | ||
| npx create-blog-doc my-blog-doc-app | ||
| ``` | ||
|
|
||
| Whatever method you use to get Blog-Doc, the process after having it is to open the folder where Blog-Doc lives with your IDE and type in the terminal: | ||
| This will create a new folder named **my-blog-doc-app** within your current directory, containing all the files you need. | ||
|
|
||
| ```bash | ||
| npm install | ||
| ``` | ||
| ### Option 2: Using `npm init` | ||
|
|
||
| After the install, to see what Blog-Doc looks like, type in the terminal the following command: | ||
| Alternatively, you can use the following command: | ||
|
|
||
| ```bash | ||
| npm run fire | ||
| npm init blog-doc my-blog-doc-app | ||
| ``` | ||
|
|
||
| This command will allow you to explore the app in the browser of your choice by visiting [localhost on port 8080](http://localhost:8080). | ||
|
|
||
| Blog-Doc comes with some posts and pages. You can now begin to create your own pages and posts from the administration, then remove the existing ones also from the administration. | ||
|
|
||
| I wish you an enjoyable trip with Blog-Doc 🚀 | ||
|
|
||
| ## Generate a static site | ||
|
|
||
| To generate a static site out of the created content: | ||
|
|
||
| 1. Click the `Admin ⚡` link. | ||
| 2. Click the `Build Static Site` link or card. | ||
| 3. Download the `site.zip` file to your disk. | ||
| 4. Extract `site.zip` and open the extracted folder with you IDE. | ||
| 5. Launch the site from the server of your IDE. | ||
| This will also create a new folder named **my-blog-doc-app** within your current directory, containing all the files you need. | ||
|
|
||
| Alternatively, type the following command in the terminal: | ||
| 3. Once installed, start Blog-Doc by typing: | ||
|
|
||
| ```bash | ||
| npm run build | ||
| ``` | ||
|
|
||
| This command will create a **\_site** folder in which all the necessary folders and files are created. You can now copy the entire content of the **\_site** folder to the server of your choice or just test it locally. | ||
|
|
||
| _**Nota Bene: In both cases, the administration part and all of it's components will be removed from the generated static site !**_ | ||
|
|
||
| ## How to use it? | ||
|
|
||
| ### Test it locally | ||
|
|
||
| Open the **\_site** folder in your IDE, I use [VS Code](https://code.visualstudio.com/) with the [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) extension.<br /> | ||
| Launch the local server and you'll be able to explore the static site. | ||
|
|
||
| ### Host it ! | ||
|
|
||
| Push the content of the **\_site** folder to a host of your choice.<br /> | ||
| There are many free hosts for static sites. The most known are: | ||
|
|
||
| - [Azure Static Web Apps](https://azure.microsoft.com/en-us/products/app-service/static/) | ||
| - [Cloudflare Pages](https://pages.cloudflare.com/) | ||
| - [Deta Space](https://deta.space/) | ||
| - [GitHub Pages](https://pages.github.com/) | ||
| - [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/#gitlab-pages) | ||
| - [Netlify](https://www.netlify.com/) | ||
| - [Render](https://render.com/) | ||
| - [Surge](https://surge.sh/) | ||
| - [Vercel](https://vercel.com/) | ||
|
|
||
| _Nota Bene: the above list can be much longer with the different services out there to host a static site !_ | ||
|
|
||
| ## RSS! | ||
|
|
||
| ⚠️ You **MUST** provide the **live URL** of your site in the **Settings page** under the administration by modifying the `siteURL` value before deploying the application. | ||
|
|
||
| At build time, a `rss.xml` file is generated in the **\_site** folder.<br /> | ||
| This file takes the live URL that you provided to generate the correct links for your feed.<br /> | ||
| _Nota Bene: the live URL **MUST** end with a slash `/` !_ | ||
|
|
||
| Of course, you **MUST** also modify `siteTitle`, `siteDescription` and `rssCopyright` in the Settings page.<br /> | ||
| You **SHOULD** replace the `siteTitle`, `siteDescription` and `rssCopyright` **values** with the ones of your site.<br /> | ||
| You **MAY** replace the `rssSiteLanguage` value with the language of your site.<br /> | ||
| A list of available language codes can be found on the [RSS language codes page](https://www.rssboard.org/rss-language-codes). | ||
|
|
||
| Bellow is a screenshot of the RSS feed of Blog-Doc in [Vivaldi browser](https://vivaldi.com/) | ||
|
|
||
|  | ||
|
|
||
| ## Sitemap | ||
|
|
||
| Like the RSS feed, you **MUST** provide the **live URL** of your site in the Settings page by modifying the `siteURL` value to generate the correct links for each page, post, tag and template as well as for the blog routes.<br /> | ||
| Please remember that the **Site URL** **MUST** end with a slash `/` ! | ||
|
|
||
| You can check the sitemap of your site under the `/sitemap` route.<br /> | ||
| At build time, a `sitemap.xml` is generated in the **\_site** folder. | ||
|
|
||
| ## Search | ||
|
|
||
| Blog-Doc has a built-in search feature.<br /> | ||
| The search functionality allows a user to make a research on **the titles** and **the contents** of the posts. | ||
|
|
||
| You can check the search of your site under the `/search` route.<br /> | ||
| At build time, a `posts.json` and a `search.js` are generated in **\_site/static/scripts**.<br /> | ||
| Also, at build time, an `index.html` is generated under the `search` folder in the **\_site** folder. | ||
|
|
||
| You can disable the search in the Node.js app as well as for the generated static site by giving `searchFeature` a value of `false` in the Settings page. | ||
|
|
||
| ## Code highlighting | ||
|
|
||
| Blog-Doc uses [highlight.js](https://highlightjs.org/) to highlight **block of code**. | ||
|
|
||
| To write **inline code**, surround your code with backticks <code>\`\`</code>.<br /> | ||
|
|
||
| To write a **block of code**, surround your block with a pair of 3 backticks <code>\`\`\`</code>.<br /> | ||
| To highlight it, provide the alias of the language for the block just after the first 3 backticks.<br /> | ||
| An example to highlight a block of CSS: | ||
|
|
||
| <pre><code> | ||
| ```css | ||
| p { | ||
| color: red | ||
| } | ||
| ``` | ||
| </code></pre> | ||
|
|
||
| We'll get the following output: | ||
|
|
||
| ```css | ||
| p { | ||
| color: red; | ||
| } | ||
| ``` | ||
|
|
||
| ⚠️ **The alias of the code language**, inline or block, **is always lowercase** ⚠️ | ||
|
|
||
| Visit the [Supported Languages of highlight.js](https://highlightjs.readthedocs.io/en/latest/supported-languages.html) to get the correct alias if you're unsure. | ||
|
|
||
| Alternatively, you can write a block of code without providing an alias, highlight.js will automatically detect the language.<br /> | ||
| If the highlighter fails to detect the correct language for a block of code without an alias, just add the desired language to the block as indicated above. | ||
|
|
||
| ## Ids for H2 till H4 in Markdown | ||
|
|
||
| Adding an `id` attribute to a heading tag, H2 till H4 only, is an optional activated feature by default. | ||
|
|
||
| This feature was built with edge cases and typing typos in mind: | ||
|
|
||
| - Regex to match curly braces ignoring everything before the last hashtag | ||
| - Replace accented characters, by their non accented letter | ||
| - Replace upper case letters by lower case one | ||
| - Remove special characters except hyphen and underscore | ||
| - Replace any number of underscore by one hyphen | ||
| - Replace any number of space by one hyphen | ||
| - Remove any number of hyphen at the beginning | ||
| - Replace any number of hyphen by one hyphen only | ||
| - Remove any number of hyphen at the end | ||
|
|
||
| To add an `id`, add a curly braces with a hashtag followed by the id's text.<br /> | ||
| The following examples will give you a better idea: | ||
|
|
||
| ```markdown | ||
| <!-- Heading tags with an id property --> | ||
|
|
||
| ## My awesome H2 title {# my-awesome-h2-title} | ||
|
|
||
| The HTML output will be: <h2 id="my-awesome-h2-title">My awesome H2 title</h2> | ||
|
|
||
| ### My awesome H3 title {# my awesome h3 title} | ||
|
|
||
| The HTML output will be: <h3 id="my-awesome-h3-title">My awesome H3 title</h3> | ||
|
|
||
| #### My awesome H4 title {# My awesome H4 title} | ||
|
|
||
| The HTML output will be: <h4 id="my-awesome-h4-title">My awesome H4 title</h4> | ||
| ``` | ||
|
|
||
| Every Whitespace is automatically replaced by a hyphen and any number of consecutive hyphens are replaced by one hyphen only. | ||
| Any number of hyphen at the beginning or the end of the id's text are removed so the following is also valid: | ||
|
|
||
| ```markdown | ||
| ## My awesome H2 title { # ----- My ----- aWEsOMe ----- h2 ----- tITlE ----- } | ||
|
|
||
| Whatever the number of whitespace characters / hyphens is at the beginning, | ||
| between the words or at the end, the HTML output will still be: | ||
|
|
||
| <h2 id="my-awesome-h2-title">My awesome H2 title</h2> | ||
| ``` | ||
|
|
||
| Anything before the **last** hashtag is ignored and special characters in the id's text are ignored too: | ||
|
|
||
| ```markdown | ||
| ## My awesome H2 title { /!@# a comment ?%^& # -my= awesome+ h2 \ ( title ) | } | ||
|
|
||
| The HTML output will be: <h2 id="my-awesome-h2-title">My awesome H2 title</h2> | ||
| ``` | ||
|
|
||
| ⚠️ Please be aware that the following special characters, if used **inside the id's text** after the **last** hashtag, will not be deleted: | ||
|
|
||
| ```txt | ||
| & will be parsed to amp (ampersand) | ||
| " will be parsed to quot (quotation) | ||
| > will be parsed to gt (greater then) | ||
| < will be parsed to lt (less then) | ||
| ``` | ||
|
|
||
| As an example: | ||
|
|
||
| ```markdown | ||
| ## Honey & Bees {#Honey & Bees} | ||
|
|
||
| The HTML output will be: <h2 id="honey-amp-bees">Honey & Bees</h2> | ||
| npm run fire | ||
| ``` | ||
|
|
||
| At build time, predefined ids will be generated into the HTML of the static site. | ||
|
|
||
| If you wish to disable this feature, set the `addIdsToHeadings` value to `false` in the Settings page. | ||
|
|
||
| ## The Gallery! | ||
|
|
||
| Since Blog-Doc turned into a CMS, I've planned to add a gallery and a way to retrieve images for the pages and posts directly.<br /> | ||
| Now it's almost done. Almost, because there is always space to bring on improvements.<br /> | ||
| For now, you can visit the gallery by hitting the `/admin-gallery` route, or go to the Administration page and click on the **Gallery** link in the menu or it's card. | ||
|
|
||
| In the global spirit of Blog-Doc, The Galley is pretty simple to use.<br /> | ||
| You'll find a drop zone where you can drop your image(s) or click on it and choose the image(s) you wish to upload.<br /> | ||
| ⚠️ Once an image added, it will be directly uploaded to the **images** folder but will not be available yet in the gallery, you **MUST** click on the **Add image(s) ✅** button to add the image(s) to the gallery ! | ||
|
|
||
| You can also delete an image from the gallery by clicking on it's **✘ DELETE** button. | ||
|
|
||
| Finally, to assign an image to a page or a post, you can, while creating or updating, choose an image from the gallery by selecting it directly from the page or post. | ||
|
|
||
| ## Themes | ||
|
|
||
| You can switch between themes and choose the design that suites your needs. | ||
|
|
||
| Blog-Doc comes with: | ||
|
|
||
| - A default theme based on the [Responsive Side Menu Layout of Pure.css](https://purecss.io/layouts/side-menu/) | ||
| - A clean-blog theme based on [Clean Blog](https://startbootstrap.com/theme/clean-blog) from [Start Bootstrap](https://startbootstrap.com/) | ||
|
|
||
| If a picture is worth a thousand words, a video is worth a million!<br /> | ||
| A 30 seconds video showing the ability to instantly change the look and feel of your site with Blog-Doc.<br /> | ||
| Click on the following image to watch the video: | ||
|
|
||
| [](https://www.youtube.com/watch?v=qaulkcZ-yu8) | ||
|
|
||
| **I'll be adding more themes to Blog-Doc over time.**<br /> | ||
| If you've coded a theme for Blog-Doc and wish to list it among the available themes, you can let me know in the Discussions of Blog-Doc's repository under the [Ideas](https://github.com/LebCit/blog-doc/discussions/categories/ideas) category.<br /> | ||
| Please keep in mind that Blog-Doc themes **MUST** only use plain JavaScript and cannot contain any code or image(s) that have publishing and/or distribution restrictions! | ||
|
|
||
| ## What's next? | ||
| This command will launch the app, which you can then explore in your browser at [localhost on port 5000](http://localhost:5000). | ||
|
|
||
| I intend to make a lot of improvements to this app in my short free time. | ||
| Blog-Doc comes with some sample posts and pages. Feel free to create your own content through the admin interface, and you can remove the default ones as needed. | ||
|
|
||
| You can take Blog-Doc as a prototype and modify it totally to use it with another design and/or another template language. | ||
| Enjoy exploring Blog-Doc! 🚀 | ||
|
|
||
| I really hope that this app will be useful in any way for a lot of people out there, I'm considering it as my personal contribution to the Node.js and Markdown communities. | ||
| ## What's Next? | ||
|
|
||
| Ideas, comments and suggestions are most welcome. | ||
| I’m excited to keep improving Blog-Doc in my spare time. Consider it a prototype that you can customize and adapt to your own design and template needs. | ||
|
|
||
| SYA,<br /> | ||
| LebCit | ||
| I genuinely hope this tool is helpful for the Node.js and Markdown communities. I welcome any [ideas](https://github.com/LebCit/blog-doc/discussions/categories/ideas), [code issues](https://github.com/LebCit/blog-doc/issues), or [code improvements](https://github.com/LebCit/blog-doc/pulls) you might have. | ||
|
|
||
| Built with ❤️ by [LebCit](https://lebcit.github.io/) | ||
| See you around! | ||
| [LebCit](https://lebcit.github.io/) |
Oops, something went wrong.