Enable html-include macro in the Jenkins tracking system

[Lars Kruse]

I'm not sure who exactly is administrating the Jira for the Jenkins community. But I have a request to - whoever it is - to allow us to do an experiment.

The thing is that we've done a small POC on actually having the documentation for the plugin in the git repo along site with the code - so that code and documentation is in the same commit on master.


Example:

In the MonKit-Plugin we have migrated the documentation as a simple minimalistic jekyll site, which is now in /docs/ folder of the repository itself:

On release the content of the /docs/ folder is merged onto gh-pages branch using 

>$ git subtree split -q --prefix docs master
13e153a1d6be094a68cc21a4bc8408eaac8d4d40
>$ git checkout gh-pages
>$ git merge 13e153a1d6be094a68cc21a4bc8408eaac8d4d40

The site is then automatically hosted by GitHub pages at

http://code.praqma.com/MonKit-Plugin

What I need at this point, it to not have to maintain my documentation twice so essentially I would like the wiki page at:

https://wiki.jenkins-ci.org/display/JENKINS/MonKit+Plugin

To contain roughly nothin but:

{jenkins-plugin-info:pluginId=monkit-plugin}

{html-include:url=http://code.praqma.com/MonKit-Plugin}

And here comes the problem then!

The html-include macro is disabled!!!!

What I would like to see is this Jira macro described here:

https://confluence.atlassian.com/display/CONF34/HTML+Include+Macro

Being enabled on Jenkins's Jira

I assume

It disabled for safety and security reasons, but I suggest that it could be enabled for safe sites.

In that case I would claim that anything hosted by GitHub pages is safe, since by design Jekyll can only generate static html.

...at least - as long as we're experimenting with this - could we possibly enable this, and then only add code.praqma.com as the single entry in the macro's white-list?

And I'll come back when we have a viable solution.

code.praqma.com is hosted by GitHub which can be verified by browsing to http://praqma.github.io ...which will redirect you there.

Cheers

/Lars

[Gavin Mogan]

> In that case I would claim that anything hosted by GitHub pages is safe, since by design Jekyll can only generate static html.

You can git push anything you want to github pages. Javascript especially.

[Lars Kruse]

...which you can disable in your browser if you don't want it to run - in that sense a {html-include:url=...} is no different than the rest of the World Wide Web which you browse every day.

[Gavin Mogan]

Afaik, html-include doesn't use iframes does it? So it would mean you could put any arbitrary code you wanted on the jenkins wiki. Right now you can't put javascript and other things there.

On Tue, Feb 2, 2016 at 9:32 AM, Lars Kruse <l...@praqma.net> wrote:

...which you can disable in your browser if you don't want it to run - in that sense a {html-include:url=...} is no different than the rest of the World Wide Web which you browse every day.

--
You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/71ZYlXhmWm0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/476daa58-f9dc-43c9-8ac7-8e8e6b7e4d97%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Lars Kruse]

I think you are referring to the {html}...{html} macro described here.

I'm asking for the {html-include:url=...} macro which is different - it specifically implements an iframe and it supports that you can configure a white list.

[Gavin Mogan]

I very well might be. I was kinda alarmed by

"Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You should only turn on these macros if you trust all your users not to attempt to exploit them. We strongly recommend leaving this macro disabled if you allow self-signed up or anonymous users to create content."

I'm not the admin of confluence though so I was just bringing up a concern.

[Richard Bywater]

I've never really used GitHub pages in anger but taking a look, I see there are Github pages that do included Javascript. 

Personally given Atlassian's warning about not using unless you trust all users, and the fact that pretty much anyone can push to the underlying Git repository and those results would show up in Confluence, I'd be quite wary of turning it on. The whitelist would potentially help but the whitelist would have to be at such a low-level that administrating it would be quite time consuming in my opinion.

My 2 cents...

Richard. 

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/3a05683f-0e60-4f59-94f1-0f5bb6b378bc%40googlegroups.com.

[Lars Kruse]

Could one of the administrators of the Jenkins Confluence wiki please chip in?

At this point - I merely want to make a proof of concept: The end goal has nothing to do with iframes or security breaches, the POC is about keeping the plugin documentation along side the code - on the master branch - as markDown (or what ever you want to use).

I realize that the solution I'm asking for may - or may not - be viable, we can decide on that later - at this point we're trying to find a simple solution to utilizing the GitHub pages jekyll build engine to automatically do all the work for us.

At this point code.praqma.com may very well be the only entry in the white list.

In Praqma we have more then 15 plugins for Jenkins, so we can actually offer to mature the work process and in the end automate a lot af work for al lot of Jenkins Plugin developers. We can later, interoperate our own build process that generates HTML using jekyll - and discriminates any JavaScript if the community sees that that is indeed a necessary requirement (personally I don't categorize JavaScript as evil, but that's not important in this discussion).

[R. Tyler Croy]

(replies inline)

On Wed, 03 Feb 2016, Lars Kruse wrote:

>
> *Could one of the administrators of the Jenkins Confluence wiki please chip
> in?*

> At this point - I merely want to make a proof of concept: The end goal has

> nothing to do with iframes or security breaches, the POC is about *keeping
> the plugin documentation along side the code - on the master branch* - as

> markDown (or what ever you want to use).

Confluence administrator chipping in!

Enabling the html-include macro would in fact be opening the wiki cross-site
scripting attacks. Regardless of whether data is hosted on GitHub or not. I can
trivially redirect an iframe from GitHub with basic HTML to a malicious site,
or if I'm feeling lazy, I can just host my malicious page on GitHub pages
without any problem.

Considering the amount of spam and traffic we endure on Confluence, I'm not
convinced that opening a security hole in our wiki for an experiment
(whitelisted or not) is the right decision for the Jenkins users who view the
wiki.

> I realize that the solution I'm asking for may - or may not - be viable, we
> can decide on that later - at this point we're trying to find a simple
> solution to utilizing the GitHub pages jekyll build engine to automatically
> do all the work for us.
>

> At this point code.praqma.com may very well be the *only* entry in the

> white list.
>
> In Praqma we have more then 15 plugins for Jenkins, so we can actually

> offer to mature the work process and in the end automate *a lot* af work
> for *al lot* of Jenkins Plugin developers. We can later, interoperate our

> own build process that generates HTML using jekyll - and discriminates any
> JavaScript if the community sees that that is indeed a necessary
> requirement (personally I don't categorize JavaScript as evil, but that's
> not important in this discussion).

While I don't necessarily like this approach, why wouldn't linking from the
wiki to the generated GitHub pages repository suffice? Some plugins do this in
very basic way already
(https://wiki.jenkins-ci.org/display/JENKINS/Pipeline+plugin) or with a mix of
static content in the wiki and more dynamic content on GitHub pages
(https://wiki.jenkins-ci.org/display/JENKINS/Job+DSL+plugin)


One of the very active discussions we've had recently in IRC and in person
(FOSDEM) has been providing better documentation integration for plugin
developers on the Jenkins primary site. I personally don't want to spend much
effort, right now, on experimenting with a half-way solution which further
fragments documentation for users.



Cheers
- R. Tyler Croy

------------------------------------------------------
Code: <https://github.com/rtyler>
Chatter: <https://twitter.com/agentdero>

% gpg --keyserver keys.gnupg.net --recv-key 3F51E16F
------------------------------------------------------

[Lars Kruse]

>why wouldn't linking from the
>wiki to the generated GitHub pages repository suffice?

...well that wouldn't index to content on search engines in context of the plugin - where we personally think that it belongs.

I believe that both job DSL and pipeline plugins are doing what they are doing - because the current state of the Jenkins confluence wiki is not accommodating their needs (documentation along side the code). And driving more and more plugins away from the wiki - as you just encouraged me to do, is not the solution. Finding a way to contain the documentation inside the wiki is.

>One of the very active discussions we've had recently in IRC and in person

>(FOSDEM) has been providing better documentation integration for plugin 

>developers on the Jenkins primary site.

Great, that you are discussing it! However, that dialog was kickstarted on my colleague's Bue's initiative at the Jenkins Code Camp in Copenhagen last summer, where he and Bobby Sandell and a handfuld of others discussed a possible solution along the lines of what Bue describes in this blog. We're implementing it.

As I mentioned earlier. Our aim here is not to encourage (or even enable) cross-site javascript attacks on the Jenkins wiki. But to take a step in the right direction of the vision that was put together last summer; that documentation should ideally be MarkDown that could live in a folder together with the source code itself, in the individual plugin repositories - and still be released as part of the deployment process and displayed on the community wiki - where it belongs.

We're just making the statement, that having the documentation in the repo instead of enforcing the manual detached update process on the Confluence wiki is doable: We're suggesting a process.

If we could - as an experiment - actually display the documentation on the confluence wiki, it would enable us to get some user feedback (an experiment, a Proof of Concept) - that something like this could be the end result, and start a debate wether or not that would be desirable.

We're prepared to convert the documentation of all our plugins to MarkDown, so there would be a substantial material to gain the feed back from.

Generating static html from the MarkDown is as easy as running jekyll build so the only blocker right now is to figure out a way to have that html displayed on the plugin page on the confluence wiki.

I'm not advocating that enabling {html-include:} is the right solution - but it is nevertheless a solution, which - by the click of a checkbox - would enable us to get som feedback on the concept. ≈ Proof of Concept.

Or it could even continue to be handled by a confluence macro. Think more in the terms of the final solution looking like this:

{jenkins-plugin-info:pluginId=monkit-plugin}

{markdown-documentation:src="/docs/"}

Where {markdown-documentation} could be a confluence macro that builds whatever is on the master branch in the $(src) path of the plugin's repository, and then just insert the generated html - at this point - provided that a) jekyll build is succesful and b) the generated code doesn't contain any java script.

>I personally don't want to spend much 

>effort, right now, on experimenting with a half-way solution which further 
>fragments documentation for users. 

I don't see why our contribution deserves to be categorized as half-way or further fragmenting documentation. Quite the opposite, Your encouragement thet we should host our documentation somewhere else is further framenting the documentation.

We're conducting an experiment - that's it. We believe it's a step in the right direction towards a whole solution, and wether or not is will fragment the documentation is exactly one of the questions, that we would like feed back on - from the users.

...and I don't see anybody asking you to spend much effort either - for starters just a checkbox setting and an entry in a white list. 

Then we can evaluate the experiment later - maybe on the next Code Camp this summer here end CPH?

[Robert Sandell]

I did mention the discussions we had on the Code Camp on the Jenkins 2.0 Summit after FOSDEM while we were discussing the plugin documentation topic, but since we haven't heard anything about it since the Code Camp we couldn't assume anything about it. And the technology and focus has changed since then.

You've had plenty of time to chime in to the website and documentation discussions that has been going on for a while on this list. And iirc KK's presentation about the goals of Jenkins 2.0, on this list, the blog, and office hours, is mentioning that Confluence will most likely die, so you've had some time to rethink and restart the discussions around how to handle the plugin docs.

So I could only assume that you weren't working on it any more and so the Summit decided on a similar but slightly different approach of building the plugin documentations into the new jenkins.io site.

Now IIUC jekyll and awestruct is pretty similar, so your work might be reusable in jenkins.io [1] so that rtyler and the website team doesn't have to do all the work themselves?

[1] https://github.com/jenkins-infra/jenkins.io

/B

--

You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/96c5fba6-5ea9-48d4-9172-ac3a39d425f6%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Robert Sandell

Software Engineer

CloudBees Inc.

[Lars Kruse]

Hi Bobby

I'm really happy to hear that Confluence will be replaced wit something else. Although I'm sorry to hear that we missed the boat.

I didn't see any threads on this topic, but I'd like to try to catch up. Can you throw me some pointers: where did you discuss this and what did you decide so far?

As we talked about 5 month's ago in CPH, the current state of the plugin documentation is a big concern of ours, and we would obviously like to help - if help is wanted.

In the meantime rtyler"s advice about abandoning ship and start hosting docs outside Confluence like Job DSL and Pipeline seems like a good advice in the light of the current situation.

So thanks for the enlightenment so far.

You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/71ZYlXhmWm0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CALzHZS2foWcxtBhhqD-CD3danV%2BcKBzQ2ZX%3Dw32AGn4Cdh22jw%40mail.gmail.com.

[R. Tyler Croy]

(replies inline)

On Fri, 05 Feb 2016, Lars Kruse wrote:

> Hi Bobby
>
> I'm really happy to hear that Confluence will be replaced wit something
> else. Although I'm sorry to hear that we missed the boat.
>
> I didn't see any threads on this topic, but I'd like to try to catch up.
> Can you throw me some pointers: where did you discuss this and what did you
> decide so far?

I'm also sorry we seem to have had a missed connection here. I'm definitely
happy to have more help with improving the Jenkins documentation world (and
with it jenkins-ci.org in general).

So we have recently moved the primary website to be statically generated from
this repository (https://github.com/jenkins-infra/jenkins.io). I refernce this
because many of the discussions we've had with regards to improving
documentation is pulling it under the main website to provide users a more
cohesive experience. Much of this discussion was held in tandem with the early
"Jenkins 2.0 mega threads" on this list (see also:
https://wiki.jenkins-ci.org/display/JENKINS/Jenkins+2.0). It's been discussed
at a few project meetings but honestly I would have trouble finding which ones
right now (low bandwidth connection)

We've also got a WEBSITE project in JIRA which captures some outstanding work:
<https://issues.jenkins-ci.org/secure/RapidBoard.jspa?rapidView=1>


Now, with all that context. the main things relevant to this conversation are:

* Site structure: having a dedicated area under jenkins-ci.org which houses
"main jenkins documentation" (i.e. getting started guides, FAQs, etc) and
plugin documentation integrated in such a way that users can easily discover
and it.
* Technical challenges of incorporating plugin documentation content into the
static site generation cycle. One of the items we discussed at the
post-FOSDEM contributor summit was using some conventional files by default
(README, GETTING_STARTED, CONTRIBUTING) from a plugin repository to generate
a basic plugin page. Then the challenge would be pulling more advanced
documentation, such as what is in a docs/ directory, into the site. The
latter I expect to be fairly non-controversial, but incorporating something
from docs/ or even a gh-pages branch might be very challenging. Part of my
reluctance to incorporate gh-pages content is that it will invariably be
styled differently than the main site, which can be confusing for users if
it is copied into the jenkins-ci.org site structure. If we were to only pull
markdown/asciidoc from the docs/ folder then we would not be able to
incorporate autogenerated pages (i.e. javadocs, doxygen, etc). I'm not sure
if that's a major problem, but something I've definitely been considering.

So that's where things are right now, I think it's very very very important to
get at least *basic* plugin documentation nested into the jenkins-ci.org
documentation tree somehow.

If you have more real-timequestions, we also discuss this topic in the
#jenkins-community channel on Freenode FWIW

> As we talked about 5 month's ago in CPH, the current state of the plugin
> documentation is a big concern of ours, and we would obviously like to help
> - if help is wanted.
>
> In the meantime rtyler"s advice about abandoning ship and start hosting
> docs outside Confluence like Job DSL and Pipeline seems like a good advice
> in the light of the current situation.
>
> So thanks for the enlightenment so far.

Again, I hope we can find a good solution in the coming weeks to make this
better than what I had suggested. I hope you'll have the time to join me in
solving the problem too, since it's clear you're passionate about documentation
like I am :)