Uploaded image for project: 'Jenkins Website'
  1. Jenkins Website
  2. WEBSITE-670

Document how to migrate plugin documentation from Wiki to GitHub

    Details

    • Similar Issues:

      Description

      I found a way which exports Wiki to a decent Asciidoc/Markdown doc automatically with Pandoc.

      1. Open the plugin wiki page. In "..." find "View Source". Save the document as HTML to the repository root (e.g. plugin.html)
      2. Call 'pandoc -o envinject.adoc --extract-media=docs/images "plugin.html"'. Asciidoc or Markdown can be used as output formats. Asciidoc is recommended for big documents, because it supports table of contents
      3. Review/edit the exported file formatting
        • Remove the macro references in the top of the document
        • If the changelog was exported, it is recommended to move it to CHANGELOG.md (even if you plan to switch to GitHub release)
        • If the document includes "Table of contents", remove this section or replace it by macros
        • If the Wiki included code blocks, they will need to be manually converted. Pandoc exports them as tables
      4. Review the content. Plugin Wiki pages are often outdated, and it is nice to review them before submitting (e.g. "slave" to "agent" renaming or "workflow" to "pipeline")

       

      Would be nice to put it in the developer documentation so that we can reference it

        Attachments

          Activity

          Show
          oleg_nenashev Oleg Nenashev added a comment - https://jenkins.io/blog/2019/10/21/plugin-docs-on-github/ https://github.com/jenkins-infra/jenkins.io/blob/master/CONTRIBUTING.adoc#moving-documentation-from-jenkins-wiki

            People

            • Assignee:
              oleg_nenashev Oleg Nenashev
              Reporter:
              oleg_nenashev Oleg Nenashev
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: