Markdown barfs on this document

[Joe Chellman]

Hi all,

I've been off the list for a little while, but I'm back with a  
question, if not a vengeance.

I've attached a sample Markdown document (the text source) that isn't  
being processed as I expect.

The rendered page is here:

http://www.shooflydesign.org/buzz/past/ 
how_do_i_make_changes_to_my_website.html

Specifically, things go awry after "How To Edit The Files".  There are  
several paragraphs thereafter that are broken, and I'm not sure why.   
Have I found a bug, or is my Markdown malformed?  Everything seems fine  
to me.  This article has been sitting around for (as you might see)  
many months now, and I found these bum paragraphs when I went to do  
some editing today.

Joe
--
Joe Chellman
http://www.chellman.org/
http://www.chellman.org/pgp_key.txt

-------------- next part --------------
### The Tools ###

There are only two essential tools for updating your pages.

1. A text editor, like [BBEdit](http://www.barebones.com/), Simpletext, Notepad, HTML-Kit, or the like.  Web pages are nothing more than text, and you need something that will edit text without trying to make it into something else.  Microsoft Word can also work, but it often tries to "help" you by hiding some of the markup and code. For our purposes, you should avoid that and use a plain text editor.
2. An FTP application, used to move files back and forth between your website and your own computer. We have recommendations for [Mac](http://www.shooflydesign.org/buzz/past/ftp_clients.html) and [Windows](http://www.shooflydesign.org/buzz/past/windows_ftp_clients.html).

### The Information ###

You'll need some information about your server, so you can login and get the files.

* The internet address, or host name, of your web server.  This is frequently your website address (www.example.com), but can also be a different name (weirdword.pair.com). This is rare now, but it can even be a number (128.2.123.123).  Regardless, your web host provides you with this information when you sign up.
* Your username, or login.  This will often look like your last name, or your first initial with your last name tacked on.
* Your password. Your web host will give you one when you first sign up.  If you're tempted to change it to something really easy to remember, don't.  It's better to have a weird password saved in your email somewhere than to use a password that a hacker can easier crack. In all likelihood, no one will touch your website.  But it never hurts to be just slightly paranoid.  If you're looking for help, read this [quick guide to choosing a good password](http://www.cs.umd.edu/faq/Passwords.shtml).

Now (finally!) you're ready to do the real work, downloading and editing the files.  Fortunately, the previous stuff only has to be done once.

### Getting Your Files, and Putting Them Back ###

FTP is used to move files between your web server, and your own computer.  The first step is to grab the files you want to change, and get them on your desktop.

1. Open your FTP application.  You should be presented with some method of connecting to a server.  Depending on the application, it could be almost anywhere.  The better ones will present you with a dialog right away, allowing you to enter your information straight away, and connect.
	If you can't figure out how to do it, don't despair.  There is online help for [SmartFTP](http://www.smartftp.com/support/howto/connect.php), [Interarchy](http://www.interarchy.com/documentation/7/how.html#how_login), and [Filezilla](http://filezilla.sourceforge.net/documentation/quickguide.htm) available.

2. After you have successfully connected, you'll see the files on your web server.  If you see several files that end with .php or .html, you have been connected directly to your web folder on the server.  If you see folders like "web" or "public_html", you've been connected to your home directory.

	Web folders on your server can be named all kinds of things.  If you see one of these folders when you login to your server, one of them is probably where your files are stored, and you should open it.

	* public_html
	* web
	* html
	* www

	Again, if you open one of these, and see files that end in .php, .html, .htm, or something like that, you're in the right place.

3. Now that you've found your files, you need to get them off the server.  In FTP-speak, this is called "getting" files.  Your FTP application *should* let you just drag the files of interest to your desktop, and download them for you.  If it doesn't let you do that, look in its menus for something called "get" or "download", or something like that.  But really, it should Just Work when you drag the files to your desktop.

	At this point, you have a copy of files from the server, and you'll be making changes.  Before you do anything else, __make a backup__.  Just create a new folder (in Windows, right-click and choose New > Folder; on the Mac, choose New Folder from the File menu), and put a copy of the file you downloaded in that folder.  This way, if you are unhappy with your changes, you can always replace the old copy.  In this way, you'll avoid being totally panicked when you call us.

	You may be wondering which files you should be downloading, which are the ones you want to edit.  This is an easy question to answer.

	1. Go to your website, and browse to the page you want to change.
	2. Look at the address bar in your browser, which display the current web address, like:
		http://www.example.com/music/mylatestalbum/lyrics.html
	3. In the above example, you want to edit a file called "lyrics.html", and you'll find it in a folder called "mylatestalbum", inside another folder called "music".  The folder "music" is displayed right after your web address, which means it's inside your web folder (or whatever that folder you found in Step 2 was called).

	One more note about file names.  If you want to edit the home page that comes up when some just goes to "http://www.example.com/", with nothing following it, you generally want a file called something like
	* index.html (by far the most common)
	* index.php (if you're working with us, this is almost as likely)
	* default.html
	* index.htm
4. At this point, you can edit your files as described below.  You'll open the files, make your changes, and save.  At this point, your changes are saved on your computer, but not on the web server.

5. To put the files back, simply drag the files from your desktop back into your FTP application window.  You may be asked if you want to overwrite the files on the server with the ones you're dragging in; if you're asked, click yes (or OK, or whatever).  That way the old files will be changed.

### How To Edit The Files ###

This is the most potentially complicated part, but it is also not overly complicated.  ShooFlyDesign keeps relatively current with website technologies, and uses two languages that you will be interested in: CSS and HTML.  CSS is what we use to control how your website looks (colors, typefaces, and much more).  HTML is the language that controls how your page is structured (where paragraph breaks appear, laying out tables of data, etc.).

Each of these languages has extensive documentation and help available all over the web.  We'll give you a very quick overview to help you make quick changes.  For anything very involved, you should spend some time reading books and online documentation, as well as [contacting us](http://www.shooflydesign.org/contact/).

#### Edit Text ####

We expect this is what you'll be most interested in doing.  In this case you're dealing with HTML, which is made up of tags, like this:

	<p>
	This is a paragraph.  It has a typoe.
	</p>
	
Those &lt;p&gt; things are tags that tell your web browser "everything between these p tags forms a paragraph".  There are similar tags for data tables (td, tr, table), lists (ol, ul, li), and headings (h1, h2, h3).  Most web pages are, if you think somewhat abstractly, structured like an outline.  This is not necessarily the most intuitive way for humans to do things, but web pages are presented and interpreted by computers, so we do things in outline form to help them.  Fortunately, outlines are not hard for humans to understand and deal with.

Moving on, you must make sure that every paragraph has those p tags around it.  If you add a paragraph, make sure it's surrounded by those tags.  Web browsers will wrap the lines in each paragraph for you, but if you want to force a line break in a particular spot, add the code &lt;br /&gt;, like this:

	<p>
	This is a paragraph.<br />
	With a typo fixed.
	</p>
	
In the first example, everything would appear on one line.  In the second, there would be a forced line break after the word paragraph.

You should also know how to make, and edit, a link.  Links look like this:

	<a href="/music/latestalbum.html">A page on my site</a> that is found
	in the music folder inside my web folder.
	
	or
	
	<a href="http://www.example.com/apage.html">A page that I like</a>
	on someone else's website.

"A" is the tag, and href is an "attribute" that determines where the link is linking to.  For pages on your website, we recommend you start with the "/" as shown in the first example, then spell out every folder that holds the page.  Don't include your web folder, but any other folder that you must open to get to the file to which you're linking should be in there.  There are other ways to link to files on your own site, but this is the one we'll start you off with.

The second link example is easier, since you can just copy the address of a page right out of your browser's address bar, and drop it in as the "href".

In both of these link examples, the actual clickable, active link, will be everything that's between the "a" tags.

There are dozens of tags all over the pages we make for you.  It would take a pretty long time, and be duplicated effort, to explain what each of them does.  If you want to change more stuff, and can't figure it out with trial and error or by looking at any of the [hundreds of websites](http://dmoz.org/Computers/Data_Formats/Markup_Languages/HTML/Reference/ "Here are several dozen to get you started.") dedicated to helping you with HTML, just [let us know](http://www.shooflydesign.org/contact/).

#### Editing Colors and Fonts ####

You will probably see a file called "yourname.css", or something.css, in your web folder.  This file (or files, there can be more than one), determines how your website looks.  Download the file and open it in your text editor.

CSS is a language that tells your web browser what to do with HTML tags.  Here's an example that covers several parts of interest:

	body {
		background-color: #FFF;
		color: #003;
	}

	p {
		font-family: verdana, arial, sans-serif;
		font-size: 12px;
	}
	
	a {
		color: #ff0;
		text-decoration: underline;
	}

The words "body" and "p" above indicate tags that this code affects.  Body is the tag that surrounds the stuff on every page that you see.  There is some other stuff in a tag called "head", most of which you don't see, but almost everything you can see is inside the body tag.  

In this case, the visible area of the page will have a white background color, and blue text.  The "color" declaration determines text color for the whole page.  Other parts of CSS can make things different colors, but whatever color is in body is the starting point.  The "#FFF" and "#003" bits are color codes -- [here are a bunch more](http://html-color-codes.com/) -- that tell your browser to show use the colors white and dark blue, in this case for the page background and text.  These numbers are used instead of words for boring reasons that we won't go into here.  Suffice it to say they're a little weird when you first encounter them, but with a [reference chart](http://html-color-codes.com/) you'll be fine.

The p declaration (or selector, as they are technically called) tells the browser to make every paragraph (surrounded by &lt;p&gt; tags as you learned above -- remember?) use type that's 12 pixels large.  It also gives the browser three options for the typeface: first it tries to use Verdana, if it's installed; if not, Arial is the next choice; and finally, if that doesn't work, whatever the default sans serif font is on the person's computer.  You can include as many fonts as you want in that list, separated by commas.

The last selector is for "a", which is the tag for a link.  The CSS tells the browser to make links yellow (see the [reference chart](http://html-color-codes.com/), and to draw links underlined.

As with HTML, there are [hundreds of websites](http://dmoz.org/Computers/Data_Formats/Style_Sheets/CSS/ "Here are several to get you started.") that describe all the intricacies of CSS.

### Finishing Up ###

Once you've made the changes you're interested in, you can copy the files from your desktop back to the server using your FTP application.  Once you've done that, be sure to visit your website and reload/refresh the page to make sure the changes appear as you want them to.

Here are some final tips:

* Avoid renaming existing files.  Remember that pages link to one another, and renaming files that have been in place and on the web for a little while will break links other websites, and pages on your own site, have made.  Links can be fixed if they break, but it's better to prevent breakage in the first place.

* If you don't know how something is done on a web page, View Source.  In the View menu of your web browser, you'll see either "View Source" or just "Source".  Choose that, and your browser will show you the HTML that was used to create the page you're looking at.  Now that you know a little bit about HTML and CSS, you will be better able to understand some of what makes web pages tick.

### Send Us Feedback ###

We realize there's a great deal of stuff we didn't cover here.  This document is a work in progress, so feel free to [send your feedback](http://www.shooflydesign.org/contact/).