Working With Content on www

Introduction

This guide is intended for anyone who would like to submit content for the www.netbeans.org site (www specifically, not the module websites like core.netbeans.org). "Submitting content" might mean corrections or updates to existing docs, completely new docs, or translated versions of some docs.

The web-content repository is under SVN version control and can be checked out. However the NetBeans Web Team have implemented a publishing system for www, and adding or editing content there is quite different than for other module websites.

Some Guidelines

Please observere the following guidelines when commiting to the site :

  • Managed Content?
    The www website is partly "managed content", owned by the Web and Evangelism teams. Any significant changes, or changes to higher-level product info pages should be approved by the Evangelism and/or web teams before publishing. If you're working on such a page, please forward your changes to webmaster and the evangelism team, including some background about why you want to make these changes.

  • New Content
    Navigation and site layout is carefully controlled, to make sure content is logically structured, in a coherent and consistent way. If you are adding new content, please check with the webmaster where would be the best place to add your file(s), and how to link that with the rest of the site.
  • Naming Conventions
    Again, if you are adding a new file, please try to use filenames consistent with existing naming conventions. These are obviously not critical, but please try to observe them. Some basic guidelines :

    • Don't use spaces in file or directory names;

    • A NetBeans version number should not be needed in the filename. Version-based directory structure is standard, so a filename need not include a version number. Eg :
      Good : kb/60/hello-world.html
      BAD : kb/hello-world-60.html
    • Don't use underscores (except for localised content language extension like index_ru.html). Eg :
      Good : community/guidelines/file-naming.html
      BAD : community/guidelines/file_naming.html
  • Images
    If you're adding images to the site, please put them under the root images_www directory. If you're creating an article with several images, it probably makes sense to create a new images dir for them, e.g. images/articles/67/midp-guide/.
  • Big Images
    Using wide images in your content will force the page to be wide, and depending on a viewer's screen resolution this may cause a horizontal scrollbar to appear - yuck! The minimum target resolution netbeans.org is designed for is 1024 x 768px, which means the main content area should be at maximum 600px wide. If you have any images wider than 600px, please create scaled-down versions of them for use in your article.
    To make sure visitors can see the real image and any detail lost by the scaling, you should link the small version to the fullsize version, so viewers can click to see it in all it's glory. Here is an example:
    <a href="../../../images_www/articles/quickstart-web/palette.png">
        <img src="../../../images_www/articles/quickstart-web/palette_small.png" border="0"></a>


    If you're not comfortable resizing your images, the Web Team can help, just get in touch with details of what you need.
  • Large Binary Files
    It is preferrable to keep large binary files out of the version controlled repositories. If you need to put a big file on the site, for example a zipfile of sources, a jar, or a .swf flash file, please use the file upload feature. This utility allows uploading and maintenance of all kinds of files. Once your file is in place, you can link to it from your html pages.

    If you don't have permissions to add a file to the utlity on www, you could try adding it to contrib.netbeans.org. If you have no permissions on any modules, contact the webmaster with details of what you're trying to do.
  • Relative Links
    Please use relative links in your html, such as <a href="../../directory/file.html">, rather than absolute (like "/directory/file.html") or fully qualified (like "https://netbeans.org/directory/file.html"). This way your (and everyone else working on the site's) local checkout is browseable, the links work, and go to your local copies.
  • Dynamic Pages
    While all content in web-content is static html, some pages are automatically generated by a content management system, and then uploaded as static snapshots. The home page is an example - several sections (headlines, articles, etc) are generated and updated dynamically by the Web Team. Any edits you make to a dynamic page will be lost when the page will be next auto-generated. All such pages include a warning comment in the html source :
      <!-- ====================================================== -->
      <!-- Please do not edit this file by hand, it is rebuilt    -->
      <!-- automatically and your changes will be lost.  Contact  -->
      <!-- webmaster for details.  Rebuilt at                     -->
      <!-- #TIMESTAMP# .................                          -->
      <!-- ====================================================== -->
      

    If you see such a warning in a file, you will need to ask the webmaster to make your changes.

  • Style and Formatting

    Please try to use standard styles, layout, and formatting for any new pages. Please refer to the templates section of the webguide, and the CSS guide for help. When in doubt, just copy the source of an existing page which suits your needs.

  • Breadcrumbs

    The breadcrumb navigation trail across the top of the page is automatically generated. The breadcrumbs are directory based - as a visitor browses deeper into the site hierarchy, an item is added to the breadcrumb list for each directory.

Got Permissions ?

If you have write permissions for web-content, and you are comfortable with how the publishing system works, it's probably fine to go ahead and commit your changes yourself. If you don't have permissions, or are not 100% comfortable with SVN and/or HTML, please see the Submitting Updates section below.

When your file is ready, the procedure to commit your files is the same for any SVN commit.

  1. Checkout the website content (web-content). If you do :

    svn co https://svn.netbeans.org/svn/web-content~web-content/trunk

    you will get the full website - including images, so it is quite large and might take a while.

  2. Make your updates/additions. web-content/www maps to the docroot of https://netbeans.org/, so for e.g. to edit

    https://netbeans.org/directory1/file2.html

    look for the file

    trunk/web-content/www/directory1/file2.html

    Edit or create your file and check your changes in a browser to make sure all looks good.

  3. If you are editing and existing file, check nobody else has edited the file since you started:

    $ svn update dir1/file2.html

    If you are adding a new file, add it to the SVN repository:

    $ svn add dir1/file2.html

    Assuming all is well, go ahead and commit it:

    $ svn commit -m "brief informative message about this update" dir1/file2.html

    You can immediately view your changes on the web site, so double check them. Browse to https://netbeans.org/dir1/file2.html .

Submitting Updates

If you don't have a netbeans.org account, or permissions to commit to web-content, and you've found something on the site that needs updating, please let us know about it. Even better, contribute the updated content!

There are a few preferred methods for submitting updates - using one of the following methods will help the webmasters to quickly and easily verify your changes and apply them.

  • Submit a patch for the HTML. This is by far the easiest for the webmasters and should ensure the fix is applied and goes live fastest. The following example uses the Unix command line SVN, if you are using Windows or a GUI client the basic procedure should be the same.

    1. Checkout the website content. If you do :

      svn co https://svn.netbeans.org/svn/web-content~web-content/trunk

      you will get the full website - including images, so it is quite large and might take a while.

    2. Make your updates. Find the file you want to update. trunk/web-content/www/ maps to the docroot of https://netbeans.org/, so for eg to edit

      https://netbeans.org/directory1/file2.html

      look for the file

      trunk/web-content/www/directory1/file2.html

      Edit the file and check your changes in a browser to make sure all looks good.

    3. Make the patch. Once you're done with your edits, from the command line, do :

      $ cd trunk/web-content/www/
      $ svn diff -u directory1/file2.html > file2.patch

      Replacing directory1 and file2.html with the real location and filename of course.

    4. Submit your patch! Either file an issue, adding the patch as an attachment, or simply email it to webmaster. Please explicitly summarise what the patch is for, and why you think it's needed.

  • Submit the whole updated HTML file. If you'd rather not use SVN or checkout the site, you can send in the updated HTML file.

    1. Browse to the print version of the page. First find the page on the www site, and then click "printable version" at the top. You'll see the same page, minus navigation, logos etc.

    2. Edit the HTML source. Select the View -> Source menu item in your browser. Select all of the source, and save it as plain text file somewhere on your system. Edit the page as you wish, and check your changes in a browser to make sure all looks good.

    3. Submit the file! Either file an issue, adding the updated file as an attachment, or simply email it to webmaster. Please explicitly summarize what the updates are, and for which file, and why you think it's needed.

  • Just submit the text of your updates!. Obviously quickest and easiest to do, but might take more time for the webmasters to check and apply your suggestions.

Submitting Links to Off-Site Docs

If there's content hosted on some other site that you think is relevant to netbeans.org, send us the link, including a brief description of what the article is about.

Translating Content

If you're interested in translating either web content or the IDE itself into your native language, we'd love your help. See the following guides to get started :

The Right Column

To add content to the right column of a page on www, you need to put that content in a special .inc file. The .inc file is not a standalone html file, it should not include any <head>, <title> or <body> tags! Just the content you want, eg styled text.

The .inc file must live in the same directory as the main parent file. The filename is critical - it should always take the form ${parent_filename}.inc.html. This is perhaps best explained by looking at some examples :

For file ...
Put right col content in ...
downloads.html
downloads.inc.html
community/releases/roadmap.html
community/releases/roadmap.inc.html
features/ide/index_ru.html
features/ide/index_ru.inc.html
kb/60/using-netbeans/ant_zh_CN.html
kb/60/using-netbeans/ant_zh_CN.inc.html
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo