diff --git a/docs/configuration.md b/docs/configuration.md index 1b2d04878..2b1bf3f04 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -616,3 +616,24 @@ window.$docsify = { topMargin: 90, // default: 0 }; ``` + +## rootRelativeImageURL + +- Type: `Boolean|String` +- Default: `false` + +Configure image URL rendering behavior when inserting markdown images when the image URL is root-relative, i.e. starts with '/'. + +By default, Docsify resolves all image paths against the current page's parent path. + +E.g. if the current path is `/advanced/guide`, `![](/assets/image.png)` would render as ``. + +```js + window.$docsify = { + rootRelativeImageURL = false // default behaviour + + rootRelativeImageURL = true // ![](/assets/image.png) renders as + + rootRelativeImageURL = 'my-root-path' // ![](/assets/image.png) renders as alt text

` + ); + }); + it('class', async function() { const { docsify } = await init(); const output = docsify.compiler.compile( @@ -165,6 +183,53 @@ describe('render', function() { ); }); }); + + describe('compiling root-relative image src path', async function() { + it('behaves normally if config.rootRelativeImageURL is set to false', async function() { + const { docsify } = await init('default', { + rootRelativeImageURL: false, + }); + const rootRelativePathOutput = docsify.compiler.compile( + '![alt text](/some-path/image.png)' + ); + const expectedCompiledPath = path.posix.join( + // must use posix here because if run on windows, file paths use backslash (\) + __dirname, + '../fixtures/default', + 'some-path/image.png' + ); + expectSameDom( + rootRelativePathOutput, + `

alt text

` + ); + }); + + it('only uses the image href if config.rootRelativeImageURL is set to true', async function() { + const { docsify } = await init('default', { + rootRelativeImageURL: true, + }); + const rootRelativePathOutput = docsify.compiler.compile( + '![alt text](/some-path/image.png)' + ); + expectSameDom( + rootRelativePathOutput, + `

alt text

` + ); + }); + + it('uses config.rootRelativeImageURL as a prefix for the compiled image path, if passed as a string', async function() { + const { docsify } = await init('default', { + rootRelativeImageURL: 'docs', + }); + const rootRelativePathOutput = docsify.compiler.compile( + '![alt text](/some-path/image.png)' + ); + expectSameDom( + rootRelativePathOutput, + `

alt text

` + ); + }); + }); }); describe('heading', function() {