Understanding HTML master pages in SharePoint 2013

Common Blog

With Design Manager in SharePoint 2013, you can convert an HTML file into a master page file. Once the conversion was successful from then the html and master page files are associated with each other. Which means if you do any edits to the html file, master page file will be automatically updated. If you have an HTML file available with you, you can directly upload the file by going to the Site Settings -> Design Manager -> Edit Master Pages -> Convert an HTML file to a SharePoint master page. Once you have uploaded the HTML file, you will see an option from context menu to convert the file to master page. Once the conversion completed the status field will be updated to either “Warnings and Errors” or “Conversion Successful” with clickable link which points to the preview of the master page.

While creating an HTML master page in SharePoint 2013 these are the important points you should remember:

  • XML Compliant: HTML file should be XML-complaint. But, there are some exceptions when you use HTML5. For example, in HTML5 we specify doctype in lowercase letters, but in XML the doctype should be uppercase…
  • Inline Styles: Adding <style> tag in <head> is not allowed. Because while conversion it will skip the <style> tag you have added in <header> section. So, you won’t see your styles applied on the pages. The Workaround is we should add a CSS file and then link that file with ms-design-css-conversion=”no” attribute. if the value set to “no” which means there is no need to do the conversion for the tag.
    Example: <link href="/Documents/Styles/Default.css" type="text/css" rel="stylesheet" ms-design-css-conversion="no" />
  • Styles to <body> tag: Applying styles to <body> tag is not the right way in 2013. Instead apply them to <div id="s4-bodyContainer"> as this tag is acts as main body div.
  • Adding Javascript: To add inline javascript code you should declare <script> tag in its own line. Otherwise it will not render on the page.
  • External javascript files: All the external javascript libraries like JQuery should be referenced before the end of <head> tag.
  • One-Directional: Always change the code in HTML file. Don’t change directly in the .master page file. Because the conversion happens one directional. HTML to master page, but not .master to HTML file. Once you complete the edits in HTML file and publish it, it will overwrites the changes to .master page file. In case if you had changed the .master file directly for quick fixes, you will lose all your changes.

Markup details/snippets in SharePoint 2013 SharePoint 2013 uses inbuilt snippet/markup tags to easily identify for the conversion. When we develop the master pages or page layouts these snippets play main role. So, below are the main snippets/markups:

  • MSO (Metadata) Tag: This tag will be used for defining the document metadata properties like content type of the document, conversion status, preview page url and many more. The parent tag under which we define these metadata is <CustomDocumentProperties> tag.
    Example: <mso:CustomDocumentProperties>
    <mso:ContentType msdt:dt="string">Html Master Page</mso:ContentType>
    <mso:HtmlDesignAssociated msdt:dt="string">1</mso:HtmlDesignAssociated>
    <mso:HtmlDesignConversionSucceeded msdt:dt="string">True</mso:HtmlDesignConversionSucceeded>
  • SPM (SharePoint Markup) Tag: This tag will be used for registering the SharePoint Namespaces and declaring SharePoint controls.
    Example: <!--SPM:<%@Master language="C#"%>-->
    <!--SPM:<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>-->

    • CS & CE: The tag CS is for Comment Start and CE is for Comment End. If we want to write comments above the tags we register we use these tags. These tags will be ignored from SharePoint Conversion engine.
      Example: <!--CS: Start Site Logo Snippet-->
      <!--CE:End Site Logo Snippet-->
    • MS & ME: The tag MS is for Markup Start and ME is for Markup End. If you want to add a snippet to the page then you should use these tags, and you can use these tags for adding SharePoint controls as well. You can get these snippets from Snippet Gallery.
    • PS & PE: The tag PS is for Preview Start and PE is for Preview End. When you are previewing the HTML page these are the blocks available for you to preview content on page and insert snippets wherever needed.

Note: Even though the post says all about master pages, the same will be applies the page layouts as well.


Related posts

Challenges bring the best out of us. What about you?

We love what we do so much and we're always looking for the next big challenge, the next problem to be solved, the next idea that simply needs the breath of life to become a reality. What's your challenge?