search

jesselang / dox

Publish markdown to Confluence as HTML
MIT License
23 stars 5 forks source link

Add edit notice to top of published pages #5

Closed mitchell-then closed 5 years ago

mitchell-then commented 5 years ago

Add a Confluence macro which states that users should not edit the page, but edit the source file. The notice can be optionally excluded with a new directive dox: omit_notice in a dox source file.

jesselang commented 5 years ago

What use cases do you think users would want to omit this notice?

jesselang commented 5 years ago

I really like this feature. I'm wondering if we should start folding options/switches like this into a single directive like this:

<!-- dox: 12345678,omit-notice,other-option-tbd,... -->

This would seem to have the benefit of simplifying how many lines need to be parsed, but does add some complexity when dox adds/updates this directive. What do you think?

mitchell-then commented 5 years ago

What use cases do you think users would want to omit this notice?

While the use cases may be rare, I'd rather provide the option to remove something we would include by default. For example, one I could think of is a page that receives a lot of traffic. The author may wish to not have the notice to reduce the amount of content on the page. Another could be that the user simply wants to control what is on the page.

mitchell-then commented 5 years ago

I really like this feature. I'm wondering if we should start folding options/switches like this into a single directive like this:

<!-- dox: 12345678,omit-notice,other-option-tbd,... -->

This would seem to have the benefit of simplifying how many lines need to be parsed, but does add some complexity when dox adds/updates this directive. What do you think?

I agree. As more options are added, the top of the dox source files may get cluttered. Moving them into a single directive would clean it up, and easily allow more directives to be added in the future.

Is this something I should look at implementing for this pull request?

atousley commented 5 years ago

Everything looks good from my perspective.

jesselang commented 5 years ago

Is this something I should look at implementing for this pull request?

No, not necessarily. I was taking the opportunity to discuss a potential overall improvement, so we can both keep it in mind as dox continues to be extended. I think we should hesitate before adding another option that would require changes to the number of lines that need to be parsed from the source files.

I'll finish reviewing this change. Thanks Mitch!

mitchell-then commented 5 years ago

I believe I have made all requested changes with the latest push.