markdown-serve/resolver

Markdown file resolver

Description:

  • Markdown file resolver

Source:
Author:
Copyright:
  • Nguyen Ly 2014-2024
License:
  • MIT License

(require("markdown-serve/resolver"))(urlPath, rootDir, optionsopt) → {string}

Description:

  • File resolver utility

Source:
Parameters:
Name Type Attributes Description
urlPath string

Relative URL path to file to try to resolve. Must start with a / and do not include the file extension
rootDir string

Full path to root folder on file system that contains files to resolve
options resolverOptions <optional>

Optional options to specify default page name and file extension

Properties
Name Type Attributes Default Description
defaultPageName string <optional>
 index

Name of default document
fileExtension string <optional>
 md

File extension of Markdown files
useExtensionInUrl boolean <optional>
 false

If true, the urlPath is expected to carry the file extension itself (eg. "/about.md"), so none is appended to it.
Default page names synthesised by the resolver still take fileExtension, so "/" and "/subfolder/" continue to resolve to "index.md".
Returns:

Full path to Markdown file if it exists and is contained within rootDir, otherwise null.
Paths that escape rootDir (eg. via ".." segments in urlPath) never resolve, so they cannot be used to read files elsewhere on disk.
A urlPath containing malformed percent-encoding (eg. "/foo%") resolves to null rather than throwing.

Type
string

Requires

  • module:path
  • module:fs

Methods

module:markdown-serve/resolver(urlPath, rootDir, optionsopt) → {string}

Description:

  • File resolver utility

Source:
Parameters:
Name Type Attributes Description
urlPath string

Relative URL path to file to try to resolve. Must start with a / and do not include the file extension
rootDir string

Full path to root folder on file system that contains files to resolve
options resolverOptions <optional>

Optional options to specify default page name and file extension

Properties
Name Type Attributes Default Description
defaultPageName string <optional>
 index

Name of default document
fileExtension string <optional>
 md

File extension of Markdown files
useExtensionInUrl boolean <optional>
 false

If true, the urlPath is expected to carry the file extension itself (eg. "/about.md"), so none is appended to it.
Default page names synthesised by the resolver still take fileExtension, so "/" and "/subfolder/" continue to resolve to "index.md".
Returns:

Full path to Markdown file if it exists and is contained within rootDir, otherwise null.
Paths that escape rootDir (eg. via ".." segments in urlPath) never resolve, so they cannot be used to read files elsewhere on disk.
A urlPath containing malformed percent-encoding (eg. "/foo%") resolves to null rather than throwing.

Type
string

(inner) contained(file, rootDir) → {string}

Description:

  • Guards against directory traversal. Returns file only if it sits inside rootDir, otherwise null.
    Exposed so that MarkdownServer#save can apply the same check to paths it builds for files that don't exist yet.

Source:
Parameters:
Name Type Description
file string

Full (already resolved) path to check
rootDir string

Full path to the root folder that file must be contained within
Returns:

file if it is contained within rootDir, otherwise null

Type
string

(inner) isFile(file) → {boolean}

Description:

  • Like exists but excludes directories. Used for candidates that are meant to be the
    final Markdown file: with useExtensionInUrl there is no extension to append, so "/sub" would
    otherwise match the "sub" directory itself and be handed to fs.readFile as if it were a file.

Source:
Parameters:
Name Type Description
file string

Full path to check
Returns:

True only if the path exists and is a regular file

Type
boolean