Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

--one-file does not interpret Markdown by default #1427

Open
jacob-carlborg opened this issue Jan 23, 2022 · 3 comments
Open

--one-file does not interpret Markdown by default #1427

jacob-carlborg opened this issue Jan 23, 2022 · 3 comments

Comments

@jacob-carlborg
Copy link

jacob-carlborg commented Jan 23, 2022

The --one-file flag does not interpret Markdown by default in the README.md file (I have not checked other non-source files).

Steps to reproduce

  1. Run the following commands:
cat << EOF >> foo.rb
# Foobar
# * asd
class Foo
end
EOF

cat << EOF >> README.md
# Foo
EOF

yard doc --one-file --no-save -o . foo.rb
  1. Open the generated index.html in the browser

Actual Output

The Markdown in the README.md has not been interpreted.

yard_no_md

Notice how # Foo is output from the README.md, but the Markdown in the foo.rb file has been interpreted and output as expected.

Expected Output

I expect the Markdown to be interpreted, this is what happens without the --one-file flag:

yard_md

Environment details:

  • OS: macOS 12.0.1
  • Ruby version (ruby -v): ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-darwin20]
  • YARD version (yard -v): yard 0.9.27
@lsegal
Copy link
Owner

lsegal commented Jan 24, 2022

This is not an issue with --one-file or YARD. By default, YARD uses rdoc style markup in .rb files. If you wish to use Markdown as your markup format, you must specify it via -m markdown, see yard doc --help.

@jacob-carlborg
Copy link
Author

I disagree. As you can see on the screenshots, the behavior is different with and without --one-file. I can post a screen recording that shows the whole flow.

@jacob-carlborg
Copy link
Author

Here's a screen recording that shows how I generate the documentation both with and without the --one-file flag. I show both results in the browser side by side:

yard.mov

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants