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

Add anchors and spacing #16

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

briandominick
Copy link
Contributor

A couple little changes in these commits.

One just improves (I think) spacing around code listings.

The other prepends anchor slugs to every heading. I've found other tools doing this, and some output processors don't add anchors later, including jekyll-asciidoc. I hope it's useful!

Applies to asciidocHandleTitle(), prepending any headline text with
a "slug" wrapped in `[[ * ]]`.

* Forces lowercase
* Replaces spaces with hyphens

Case and hyphenation changes are not required,
but they tidy up the anchors.
@ggrossetie
Copy link
Owner

I think this features should be configurable.
Maybe it's the right time to create a configuration panel:

AFAIK we can create a custom dialog and use Property service to store and serve data.
Wdyt ?

@briandominick
Copy link
Contributor Author

briandominick commented Jul 14, 2016

Yeah, I thought of that as well. In some cases I would find the anchors superfluous, though the s&r regex stripping them is simpler than adding them ;-)

We could also consider allowing such alterations inside the modal after the main conversion takes place. It might be nice to do this for certain types of cleanup that I've had to do post-migration, that maybe were due more to the way my docs were formatted than the script itself. But I think re-running the "server-side" conversion is easy enough, so you could just toggle those options as needed.

I don't know how trivial it is to add these features. This is my first contrib to a Google Apps project. I'm definitely in, though. I need this tool ;-)

@ggrossetie
Copy link
Owner

I don't know how trivial it is to add these features. This is my first contrib to a Google Apps project. I'm definitely in, though. I need this tool ;-)

This is my first Google Apps project too 😄

We could also consider allowing such alterations inside the modal after the main conversion takes place. It might be nice to do this for certain types of cleanup that I've had to do post-migration, that maybe were due more to the way my docs were formatted than the script itself. But I think re-running the "server-side" conversion is easy enough, so you could just toggle those options as needed.

Why not but a configuration panel will avoid to re-running the conversion.
I will try to find some time next week to experiment.

@briandominick
Copy link
Contributor Author

+1 for sure. I think you're right about the approach. Count me in for several hours of tinkering and testing.

One other configurable preference I would use is converting headings to # instead of =. Our product docs use that notation, and our engineers are used to Markdown (from GitHub, mainly, of course). There are quite a few such preference possibilities in Asciidoc, so a framework for adding them would be smart.

@briandominick
Copy link
Contributor Author

We can hold this branch off until we slip those conditionals in, no worries. The add-on testing in GDocs is relatively easy to use for production.

@ggrossetie
Copy link
Owner

@briandominick Do we really need to explicitly define anchors ? You could add :sectanchors: attribute and let Asciidoctor do the job for you no ? http://asciidoctor.org/docs/user-manual/#anchors

One other configurable preference I would use is converting headings to # instead of =

I think @mojavelinux will disagree on this one 😉
Asciidoctor supports (some) Markdown syntax but we do encourage users to use the Asciidoctor syntax. What do you think Dan ?

If we decide to not include this feature, then creating a configuration panel, to choose to add an extra space or not, is not worth it I guess.

However I've started experimenting on a configuration panel and it's quite easy so feel free to add more features 😄

@briandominick
Copy link
Contributor Author

@Mogztter So this is funny: it was only this weekend that I realized # is not actually officially supported for title/heading marks! The first AsciiDoc project I ever took over used them, for whatever reason, and I never noticed they're undocumented. I've changed my mind on this for the current project, actually. If we're going to be using markdown at all, I actually like this being one of the distinctive characteristics so you know what language you're supposed to be using. So yeah, I'm dropping the # setting request.

I do think explicit anchors can be useful. I got the idea of forcing them from another converter; I don't recall which. I think what I like about them is they can stay the same even if the heading they mark gets changed, so you don't get broken links and xrefs. I'm not really sure if that's best practice for team usage. I've had the luxury(?) of being the only one directly using my AsciiDoc files until now. I don't think it's the end of the world at all to not offer this, but it seems simple. This script is incomplete, though -- it needs more replacements, such as / and other symbols.

Good to know config is easy. I'll draft off your achievement when you commit the first one ;-)

@mojavelinux
Copy link

mojavelinux commented Jul 20, 2016

@Mogztter anticipated correctly, I also prefer generating the document using = headings. Asciidoctor supports some Markdown syntax to ease migration and to provide a stop-gap solution when the document has to be parsed by a Markdown processor (like on npm), but we should always be gravitating towards the official AsciiDoc syntax.

As for the section anchors, I think we're getting section IDs and anchors confused. The [[anchor-name]] line sets the HTML ID for a section. If this line is not present, and the sectids attribute is set (as it is by default), then an ID is auto-generated. These IDs are not visible to the user, but allow deep linking to that section of the page.

If you want to see a physical anchor or link, then you must set either the sectanchors or sectlinks attribute.

For mature documents, it's a good idea to set the ID explicitly for reasons @briandominick explained. So I do think it is a good option to have. The auto-generated ID is to save typing in early drafts and for simpler documents.

If we set auto-generated IDs, however, we should use the modern syntax.

[#anchor-name]
= Section Title

@briandominick
Copy link
Contributor Author

+1 to generating IDs, not anchors, formatted as: [#anchor-name]!

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

Successfully merging this pull request may close these issues.

3 participants