generate pages from markdown files with dynamic routes, 0 effort, 0 boilerplate.

Purpose

Allow developers to build such a page with next-markdown:

cf. https://chakra-ui.com/guides/integrations/with-storybook

TODO

List all files (done #5)

List every files when rendering index.md. Props should look like:

{
  ...
  html: string,
  nextmd: [...],
  files: [
    {
       ...
       html: string,
       nextmd: [..., ...],
    },
    ...
  ]
}

List previous / next files (won't do, not necessary)

This can be actually achieved with files[n-1] and files[n+1].

Table of Contents (done #8)

List markdown content headings + add anchors

Provide an example

Please provide an example in examples/.

Discussions

[x] Maybe we should rename posts attribute. It is misleading since it's not asked to be a "blog post" (as we can see, it can also achieve documentation purpose) => done, posts has been renamed to files, cf. #5

Please, help.

Problem

Right now I have no proper solution:

• I tried to use npm link but, for every changes in next-markdown/src/index.ts, I need to execute cd examples/blogging && rm -rf node_modules/next-markdown && npm link. Very painful.
• copy/paste next-markdown/src/index.ts and use it locally in an example, so when I am done, I copy/paste back to next-markdown/src. Very painful and ugly...
• I cannot write tests. I tried exporting a next-markdown function (eg. export getNextmdFromFilePath = (..)=>{..}) but import { getNextmdFromFilePath } from '../'; in file __tests__/index.test.ts failed with error Module '"../index"' has no exported member 'getNextmdFromFilePath'

Wanted

I don't have the time (and knowledge yet) to setup properly the project this way:

• ability to write tests...
• live test: everytime next-markdown/src/index.ts changes, tests are ran
• dev mode with lie reloading: having a project where everytime next-markdown/src/index.ts changes, the project updates
• code splitting. For now if I create for example an utility file next-markdown/src/utility.ts the published npm library does not work (module not found)

Thank you

Any help is much than appreciated 🙏

hello:1 GET http://localhost:3000/hello 500 (Internal Server Error) index.js?20a9:314 Uncaught at Object.next-markdown (file:///Users/kr.mao/Workspace/codesdancing/.next/server/pages/[...nextmd].js:32:1) at webpack_require (file:///Users/kr.mao/Workspace/codesdancing/.next/server/webpack-runtime.js:33:42) at eval (webpack-internal:///./src/pages/[...nextmd].jsx:8:71) at Function.webpack_require.a (file:///Users/kr.mao/Workspace/codesdancing/.next/server/webpack-runtime.js:106:13) at eval (webpack-internal:///./src/pages/[...nextmd].jsx:1:21) at Object../src/pages/[...nextmd].jsx (file:///Users/kr.mao/Workspace/codesdancing/.next/server/pages/[...nextmd].js:22:1) at webpack_require (file:///Users/kr.mao/Workspace/codesdancing/.next/server/webpack-runtime.js:33:42) at webpack_exec (file:///Users/kr.mao/Workspace/codesdancing/.next/server/pages/[...nextmd].js:52:39) at (file:///Users/kr.mao/Workspace/codesdancing/.next/server/pages/[...nextmd].js:53:28) at Object. (file:///Users/kr.mao/Workspace/codesdancing/.next/server/pages/[...nextmd].js:56:3) getNodeError @ nodeStackFrames.js?aca3:40 eval @ index.js?20a9:313 setTimeout（异步） _callee$ @ index.js?20a9:301 tryCatch @ runtime.js?96cf:63 invoke @ runtime.js?96cf:294 eval @ runtime.js?96cf:119 asyncGeneratorStep @ index.js?20a9:28 _next @ index.js?20a9:46 Promise.then（异步） asyncGeneratorStep @ index.js?20a9:37 _next @ index.js?20a9:46 eval @ index.js?20a9:51 eval @ index.js?20a9:43 _initNext @ index.js?20a9:363 initNext @ index.js?20a9:366 eval @ next-dev.js?3346:38 ./node_modules/next/dist/client/next-dev.js @ main.js?ts=1646807645629:600 options.factory @ webpack.js?ts=1646807645629:685 webpack_require @ webpack.js?ts=1646807645629:37 webpack_exec @ main.js?ts=1646807645629:1399 （匿名） @ main.js?ts=1646807645629:1400 webpackJsonpCallback @ webpack.js?ts=1646807645629:1268 （匿名） @ main.js?ts=1646807645629:9

Context

At the time of writing, next-markdown support nextjs "catch all routes", meaning you need to add a [...nextmd].js in your pages and create an index.js for the home page.

Purpose

We want to create a website (including the home page!) with markdown. To allow creating home page we need to use "optional catch all routes".

Todo

next-markdown should work with [[...nextmd]].js

Closes #6

Work in Progress:

• [x] lib is bundled using parcel
• [x] lib type: module
• [x] examples uses the local lib
• [x] examples hot-reload when lib code base is edited
• [x] npm install [email protected] works
• [x] unable to run tests yet :(

Typescript supports .js imports for .ts files. see why here : https://github.com/microsoft/TypeScript/issues/16577#issuecomment-754941937

Either that or :

• use a bundler (IMO overkill for the size of next-markdown)
• use a post-processor typescript plugin to append .js file extensions to relative imports after compilation

Purpose

Allow to customize the YYYY-MM-DD rule for given folder.

Thus allowing specified folder to have custom rule to sort content:

pages-mardown/
├ docs/
   ├ feat-A-doc1.md
   ├ feat-A-doc2.md
   ├ feat-B-doc1.md
   ├ feat-B-doc2.md
   ├ feat-B-doc3.md
``

## how to?

Please take example to the function `include` in the NextMarkdownConfig type, where `include` has a default behavior that can be overridden.

Closes #4 Closes #15 (keep next-markdown simple, getStaticPropsForNextmd can do the job)

This might be the most simple way to test this PR in your project, run npm install "https://github.com/frouo/next-markdown.git#feature/documentation"

Purpose

In some circumstances, you likely want to use subfolders to classify your markdown files. For example when writing docs.

So you want a way to bypass the default next-markdown dynamic routes.

Considered solution

✋ default dynamic routes MUST remain because it covers 99% of use cases. We all love how nextjs works with /pages. . Eg: path/to/projects.md will match /path/to/project.

We could have a .nextmd.config.json file at the root of a given folder to bypass how next-markdown will consider this folder's subfolders.

# .nextmd.config.json

{
  "flatten": ["examples", "features"]
}

Discussion

Tell me what you think in comment. Thanks

tsc build output to es2020 modules does not append .js extensions to dist files. Either use a builder to alleviate this or force single file output.

node ESModule resolution requires .js extensions in imports !

Split the lib in several parts

• npm install @nextmarkdown/core : contains everything but the markdownToHtml logic (commonjs lib)
• npm install @nextmarkdown/markdown-to-html : will contain all the logic to convert markdown to html with remark / rehype plugins dependencies (esm module lib because rehype-stringify is ESM only).
• npm install @nextmarkdown/mdx : will contain the next-mdx-remote logic.

Finally npm install next-markdown would install, by default, both @nextmarkdown/core and @nextmarkdown/markdown-to-html so it is really easy to get started with next-mardown + covers 80% of the usage cases.