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

Standardize title code style for jenkins.io asciidoc files

    Details

    • Type: Task
    • Status: To Do (View Workflow)
    • Priority: Minor
    • Resolution: Unresolved
    • Component/s: content
    • Labels:
      None
    • Similar Issues:

      Description

      In recent PR (https://github.com/jenkins-infra/jenkins.io/pull/1795) a contributor added :doctitle: to a page.  This is a completely valid way to add title to a asciidoc page.  But that is not how we do it on the majority of pages on jenkins.io.  (We generally use title: in the yaml front-matter).  

      Even more confusing is that none of these is required. 

      With a bit of testing, I determined that the following three examples produce the same output:

      A. 

       

      --- 
      layout: chapter
      title: Installing Jenkins
      --- 
      
      The procedures on this page are for new installations of Jenkins on a single/local machine.
      
      

       

      B.

       

      ---
      layout: chapter
      ---
      :doctitle: Installing Jenkins
      
      The procedures on this page are for new installations of Jenkins on a single/local machine.

      C.

       

       

      --- 
      layout: chapter
      --- 
      = Installing Jenkins
      
      The procedures on this page are for new installations of Jenkins on a single/local machine.

       

       

      Version "A" seems to have the better behavior in `make run` local testing (awestruct dynamic rebuild).  C seems needed to make PDF generation of Jenkins Handbook work right. 
      So, we use A and then add C for handbook pages.
      We mention A in https://github.com/jenkins-infra/jenkins.io/blob/master/CONTRIBUTING.adoc#adding-a-blog-post but not under documentation.  

       

      We should pick a standard way to do this and programmatically enforce it on all adoc pages. 

      Reference: 

      https://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FDocument:doctitle

        Attachments

          Activity

          Hide
          rtyler R. Tyler Croy added a comment -

          Keep in mind that titles are also rendered into the PDF for the handbook. The YAML frontmatter only appears for HTML-rendering through awestruct

          Show
          rtyler R. Tyler Croy added a comment - Keep in mind that titles are also rendered into the PDF for the handbook. The YAML frontmatter only appears for HTML-rendering through awestruct

            People

            • Assignee:
              Unassigned
              Reporter:
              bitwiseman Liam Newman
            • Votes:
              1 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated: