beginner-guide.md 4.9 KB
This is a guide to setting up microblog for absolute beginners.
1. Download these programs:
Once python is correctly installed, you can use it to download:
Python is a programming language. We will use it to run the microblog code.
dateutil and toml are modules. Modules are subcomponents of python that do specific tasks, but which you might not need in every project. dateutil helps to format dates, and toml reads the settings file.
2. Download the microblog code
- go to the front page of this project
- on the right-hand side, above the list of files, click the download icon
- download in either .zip or .tar.gz as you prefer
- extract the contents of the .zip/.tar file
3. Copy all the files in /example into the same folder as microblog.py
Your folder now includes:
- microblog.py
- demo.txt
- default.tpl
- settings.toml
- timeline.css
as well as some other stuff.
4. Open a command window
- In the folder, Shift+Right Click anywhere in the white space to open a list of options
- Click 'Open command window here'
A box will pop up.
5. Run this code
python microblog.py ./default.tpl ./demo.txt > result.HTML
What does this code do?
- python - use the program 'python'
- microblog.py - to run this file of code
- ./default.tpl - combine this webpage template
- ./demo.txt - with this file of posts
- > result.html - save the output as a new file, called result.html
Hint: you can name the output file whatever you like (for example, blog.html or index.html)
6. Look at what you've got
In this folder, there will be a new file called result.html. Open it. Congratulations - you have made your first microblog!
Some other things have been generated:
- pages: !I don't know what this does! but probably, once your blog has a certain number of posts, this folder handles 'go to page 30' style backreading
- tags: this folder contains one page for each tag your blog uses, so you can see all pages tagged a certain way
Whenever you re-run the code from step 5, all these files will be deleted and overwritten with a new version.
7. Time to blog
Look at the example in demo.txt for how to lay out posts.
- The first line of the file must always be blank
- The last two lines of the file must always be blank
- There should be no MORE than two blank lines at the end
- Leave one blank line between each post
- Leave no blank lines inside of a post
- Always add new posts at the top
Typing in a program like VSCodium will make it easier to see if there are additional 'blank lines' saved in you code where they aren't supposed to be (compared to using Notepad, for example)
8. Upload to your website
Whenever you want to update your blog, re-upload these files and folders:
- folder: pages
- folder: tags
- folder: images
- folder: thumbs
- result.html
- timeline.css
- style.css
A good place to put your blog if you are making a hobby website for the first time is neocities
9. Setting up images
The code expects there to be some other files and folders, which do not come as part of the example setup
- create a folder called 'images'
- create a folder called 'thumbs'
Put full-size pictures in images. Make a thumbnail version of each, under the same name, and put them in thumbs.
(a thumbnail version means 'the same image, but a lot smaller' - it means your page will load faster, and be easier on bandwidth and slower connections)
microblog will display .jpg and .png files.
10. Adding a style
The default.tpl template code links to a file called style.css. This file does not exist yet - you can create it.
template.css handles how areas of your microblog are laid out. It doesn't include any information about how to display it (apart from some borders to show where the boxes are). If you make a separate styles.css file, containing fonts, background images, better borders and more, then that makes it faster to swap styles in the future without worrying about changing the layout by accident.
(But as you become more skilled with CSS, there are lots of different ways you could display the layout boxes too)
11. Hide interaction
At the bottom of each blog post, microblog generates three links for interacting with your blog. If you're not ready to set these up yet, add this code to your style.css:
.buttons {display: none;}
Now they simply won't appear.
12. Using tags
Tags cannot contain a colon (:) or a pipe (|) but can contain a hyphen (-) - for example if you want to make subtags.
Error Messages
Failed to interpret a date from a string. Your file or posts may be malformed. Check if your file starts with a line break
This error message means there is a mistake in content.html (or whatever your blog post content file is called). Check #7 - Time to Blog and ensure your file is laid out correctly.