improve documentation regarding embedded markdown