Dot Comments Tutorial

There are five main steps you need to complete in order to activate .mac comments on your weblog.

Step 1: Add HTML structure to your weblog entry pages

You'll probably want separate comments for each entry on your weblog. To do this, you'll need to place the following code in the HEAD tag of each entry for which you want to use comments:

<script language="javascript" type="text/javascript"><!--
  var GUID = 'index.html';
  var commentsActivated = true;

The GUID variable doesn't actually do anything (as far as I can tell), but the commentsActivated variable tells .mac to enable comments for the current page. The linked script is hosted on Apple's servers, and is what powers the rendering of comments.

The following HTML markup is where comments actually get rendered. You'll notice that it's just a bunch of div tags. The JavaScript that powers the commenting system dynamically gets references to the div tags here and renders the comments when the JavaScript code is called. You'll need to place the following code somewhere within the BODY tag of each HTML page for which you want to display .mac comments.

		<div id="comment_layer">
			<div id="comment_title">
				<div class="graphic_textbox_style_default" id="id2">
						<div class="graphic_textbox_layout_style_default">
							<div class="paragraph Comment_Count"><span><span id="count_0"></span></span><span> </span><span id="manage_comments_0" class="light"></span></div>
			<div id="comment_list"></div>
			<div id="comment_footer">
				<div class="graphic_textbox_style_default" id="id3">
						<div class="graphic_textbox_layout_style_default">
							<div class="paragraph Comment_Add_A_Comment"><span id="post_link_0"></span></div>

Finally, the body tag needs to be include the following onload function:

<body onload="initComments();">

Step 2: Add HTML structure to your main weblog page

Many main weblog pages include comment counters, showing how many comments have been written for the entry, even if the comments don't directly appear on the main page. To accomplish this, you'll need to modify the HTML of your main weblog page.

You'll want to add this HTML code wherever you want a comments counter to appear on your main weblog page:

<script language="JavaScript" type="text/javascript">var entryURLs = {
    'index.html' : {}
<script language="JavaScript" type="text/javascript"> initSummaryComments('Category_folder/Entry_folder/index.html');</script>

Note the relative URL inside the writeScriptLink() and initSummaryComments() calls. For each time you want to show a comment counter, this variable needs to be the URL of that entry page relative to the main weblog page. So, for example, if my main weblog page is at index.html, and an entry page is at /Category_folder/Entry_folder/index.html , then I'll want to put in the relative URL 'Category_folder/Entry_folder/index.html', as I did in the above code snippit. Note that you need to enclose the relative URL by single quotes.

Step 3: Add supporting JavaScript routines to your webpage

If you don't have a separate JavaScript file for your weblog, I suggest that you use one. This will keep your webpage HTML cleaner. Create a new file, and name it something like "MyWeblogComments.js".

Now, go to the URL and copy the entire contents of this file. Paste it to the bottom of your MyWeblogComments.js file (or whatever file you use for JavaScript functions). (This step is necessary if you plan to publish your weblog to the URL; that is, if your weblog folder resides within the "Sites" folder on your iDisk. If you want to use the newer subdomain and put your weblog files inside the "Web" folder on your iDisk, you can simply link to the script file on the server directly. Please note, using the subdomain is not advised.)

Once you've pasted the contents of comments.js into your MyWeblogComments.js file, you have to make two small tweaks. Find the following line:

var commentsURL = location.pathname + '?wsc=entry.js&ts=' + new Date().getTime();

Change it to this:

var commentsURL = '' + location.pathname + '?wsc=entry.js&ts=' + new Date().getTime();

Then find this line:

JSONScript.setAttribute('src',location.pathname + '?wsc=entry.js&ts=' + new Date().getTime());

and change it to this:

JSONScript.setAttribute('src','' + location.pathname + '?wsc=entry.js&ts=' + new Date().getTime());

This will allow your weblog on the URL to retrieve comments from the subdomain, the only subdomain of that the comments system currently supports.

Now, add the following code to the bottom of the MyWeblogComments.js file as well:

var time = new Date().getTime();

var entryURLs = {
    'index.html' : {}

var commentsActivated = true;

function writeScriptLink(url)
	var location_array = location.pathname.split('/');
	var amended_location_string = '';
	var i = 0;
	var count = location_array.length;
	for (i = 0; i < (count-1); i++) {
		if (location_array[i] != '') amended_location_string = amended_location_string + location_array[i] + '/';
	document.write('<script src="' + '' + amended_location_string + url + '?wsc=summary.js&ts=' + time + '" type="text/javascript"></script>');

function initSummaryComments(url) 
	var commentCount;
	if (entryURLs['index.html'].comments) {
		if (commentCount !== null) {
				document.write('<a href="' + url + '#comment_layer">' + commentCountString(entryURLs['index.html'].count) + '</a>');
		commentCount = null;

Once you've done this, you need to add the following line inside the HEAD tag of all HTML files where comments are used -- each weblog entry page, and the main weblog entry page need to have this line:

<script language="JavaScript1.2" src="MyWeblogComments.js" type="text/javascript"></script>

Please note that you'll need to replace "MyWeblogComments.js" with a valid URL to the actual file on your iDisk. So, for example, if you have a page called "index.html" in the same folder as "MyWeblogComments.js", then you can simply put in "MyWeblogComments.js" for the "src" attribute, as above. If, instead, you have a page called "index.html" that's inside a folder called "Category_folder", and this folder is next to "MyWeblogComments.js", then you'll need to put in "../MyWeblogComments.js" for the "src" attribute instead so that the page correctly finds the JavaScript file.

If you really want to be safe, you can simply place the full URL as the "src" attribute. For example, you could put in "" in for every file.

Step 4: Publish your weblog

This is very important. You need to publish your weblog before you activate .mac comments for that entry. Also, remember, if you have the local iDisk turned on, you will need to sync your iDisk before proceeding to the next step.

Step 5: Activate .mac comments for each URL

You'll need to activate .mac comments once per entry. So if you have three entries on which you want comments enabled, you'll need to activate .mac comments three times. This is where Dot Comments comes in.

Please note, I'm assuming you access your weblog using a "" URL. If you're instead using the newer "" URL, I strongly advise you switch back to the older "" URL if you want to use .mac comments. I'll explain why later. However, this step is identical regardless of which subdomain you use.

Assuming you've completed step 4 (which is necessary before completing step 5), visit the webpage for the entry for which you want to activate comments. You want the "" or "" URL, not the file:/// URL. Copy this URL to the clipboard.

Now open Dot Comments. Put your .mac username in the top field, your .mac password in the second field, and paste in the URL you just copied to the third field. Now all you have to do is click the "Activate Comments" button.

At this point, if you have local iDisk synching activated, you again need to sync your iDisk to the .mac servers.

Once that's done, you can test the comments for that entry. Just click the "Add a Comment" button, and a page will open that will allow you to enter comments. If the comments form comes up, all is well. If all is not well, you will see an error message displayed on the page rather than a comments form.

That's it, you're done! Remember, you need to activate comments for each entry URL.

What are the caveats with using .mac comments?

Well, there's only one, really. As I mentioned before, I strongly encourage you to use the domain rather than the domain. This is because of the details behind the .mac comments system.

iWeb publishes its blog pages to the subdomain. (If you use iWeb, you should see a "Web" folder at the root level -- iWeb publishes to this folder, and they are accessed via the subdomain.) The .mac comments system uses the URL of the page to activate comments. If an HTML file exists at the URL, then .mac comments will be enabled. If the HTML file does not exist at that location, .mac comments will remain disabled whether or not you activate them via Dot Comments.

Unfortunately, if you even touch the contents of the HTML file after it has been activated, any comments that have been associated with that entry will be obliterated. Gone. You won't be able to bring them back. So, if you publish your weblog to the subdomain (by placing your HTML files in the "Web" folder of your iDisk), you'll only get one shot: if you want to modify the page later, you'll lose all your comments for that entry.

This is obviously unacceptable in many situations, so Dot Comments works around that. When you copy in a URL to Dot Comments and click the "Activate Comments" button, Dot Comments places a dummy HTML file at the appropriate URL. That way, the .mac comments system will think there is a valid HTML file at the URL and will activate the comments for that entry. (So basically, Dot Comments will place an appropriate dummy file in the "Web" folder of your iDisk.) Furthermore, you'll be able to modify the HTML file in the subdomain at will, without fear of losing any existing comments. (That means your weblog pages should reside in the "Sites" folder of your iDisk, which are accessed via the URL.)

You can publish your weblog to the "Web" folder if you wish, and Dot Comments will happily accept URLs for comment activation. (With URLs, no dummy file is created.) But given the above caveat, I strongly recommend against publishing to the "Web" folder of your iDisk.

Sample Demonstration

If you want to see a sample weblog with .mac comments activated, look no further than my own weblog, Technological Supernova (no longer working). I just recently switched over to .mac comments, and you're welcome to browse around and see how it looks.

Alternatively, you can add a .mac comment directly to this tutorial. Just click the "Add a Comment" link below.