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.

Sign up for GitHub

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

Jump to bottom

#398: Update asciidoc-writers-guide.adoc #655

Closed
wants to merge 1 commit into from
Closed

#398: Update asciidoc-writers-guide.adoc #655

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/asciidoc-writers-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,8 @@ include::{includedir}/xref.adoc[]

include::{includedir}/xref-relative.adoc[]

TIP: The xref inline macro by default resolves the link to HTML, to create a relative link to an asciidoc file in another subdirectory include `ifdef::env-github[:outfilesuffix: .adoc]` below the document header and drop the ".adoc" extension after the filename.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a method which is more neutral (support any output or source format). I canimagine there are more edit environents than GitHub?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ecki, Thanks for pointing out, it shouldn't indeed be limited to just GitHub.
I am not aware of any generic way, will explore and update the PR.

Copy link
Member

@mojavelinux mojavelinux Apr 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's important to note that the xref macro only links to another file if the target ends in a hash suffix (e.g., # or #anchor-name). The # is how Asciidoctor distinguishes between an internal xref and an external xref.

Is there a method which is more neutral (support any output or source format).

The env-* attributes are set by the integrations. For example, the code that runs on GitHub (and GitLab) sets the env-github attribute. You should expect that each integration has a similar attribute. For example, Awestruct sets env-site. We've tried to introduce generic attributes where possible, but in some cases like GitHub, the environment is so unique that it really only applies to that specific integration.

Btw, the browser previews also need the outfilesuffix to be .adoc. Both the Chrome and Firefox plugin set this value by default now. You can also use env-browser in those environments.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Eventually, we'll want to document all these environment attributes in the user manual. At the time of this writing, they are still evolving.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to see outfilesuffix set to .adoc by default on GitHub. There's an issue tracking that change. See github/markup#519


Image references are similar to links since they are also references to URLs or files.
The difference, of course, is that they display the image in the document.

Expand Down